Repository navigation
macOS
Complete documentation for StreamTV on macOS.
Canonical guides (prefer these): ARCHITECTURE.md · Player preview · Soft deploy · Plex video hold · TunarrRAM · Backup · Auto-Healer (production defaults off). This page is a large historical amalgam — if it conflicts, trust the linked guides.
StreamTV is an efficient online media streaming platform that emulates HDHomeRun tuners for integration with Plex, Emby, and Jellyfin.
On first launch after Python setup (or in Settings → AI Self-Recovery), choose:
-
Apple Foundation Models (macOS 26+ / Apple Intelligence) — on-device bridge on port
11435 - Ollama (optional on any supported macOS)
- No AI — deterministic heal scripts only
Production: auto_healer.enabled and apply_fixes default false (advise-only until an operator change window). See Foundation Models recovery and Auto-Healer.
Automatic portable zips and first-launch restore: Backup and restore.
- StreamTV Core: Complete streaming platform
- Installation Scripts: Automated setup for macOS
- Documentation: Complete guides and API documentation
- Example Configurations: Ready-to-use channel examples
Preferred: install the signed DMG from Releases (tip v1.4.2).
From a source checkout:
-
Run the installer:
bash packaging/macos/install_macos.sh
-
Start the server:
./start_server.sh
-
Access the web interface: Open http://localhost:8410 in your browser (
/playerfor browser preview)
- Full HDHomeRun API compatibility
- SSDP auto-discovery
- Multiple virtual tuners
- Direct Plex/Emby/Jellyfin integration
- M3U playlist generation
- XMLTV EPG guide
- Channel management
- Schedule-based playout
- YouTube: Direct streaming with authentication
- Archive.org: Access to public domain content
- PBS: Live and on-demand PBS streams
- Continuous: Timeline-based continuous playout (ErsatzTV-style)
- On-Demand: Start from beginning or saved position
Complete installation guide for StreamTV on macOS.
Run the automated installation script:
./install_macos.shThis script will:
- Check and install Python 3.8+ from python.org
- Install FFmpeg from official sources (Homebrew as fallback)
- Set up a virtual environment
- Install all Python dependencies
- Configure the platform
- Initialize the database
- Create launch scripts
- Optionally start the server
If you prefer to install manually:
Download and install from python.org:
- Choose the macOS installer for your architecture (Intel or Apple Silicon)
- Run the installer and follow the instructions
- Verify installation:
python3 --version
For Apple Silicon Macs, download from evermeet.cx:
curl -L -o /tmp/ffmpeg.zip https://evermeet.cx/ffmpeg/ffmpeg-6.1.1.zip
unzip -q -o /tmp/ffmpeg.zip -d /tmp/
sudo mv /tmp/ffmpeg /usr/local/bin/ffmpeg
sudo chmod +x /usr/local/bin/ffmpegbrew install ffmpegpython3 -m venv ~/.retro-tv-simulator/venv
source ~/.retro-tv-simulator/venv/bin/activatepip install --upgrade pip setuptools wheel
pip install -r requirements.txtcp config.example.yaml config.yaml
# Edit config.yaml as neededpython3 -c "from streamtv.database.session import init_db; init_db()"After installation, you can create channels using:
- The web interface at http://localhost:8410/channels
- The API (see API documentation)
- YAML import files (see SCHEDULES.md)
Example using the script:
python3 scripts/create_channel.py --number 1 --name "My First Channel"python3 -m streamtv.main-
Virtual Environment:
~/.streamtv/venv -
Launch Script:
~/.streamtv/start_server.sh -
Service Plist:
~/Library/LaunchAgents/com.streamtv.plist -
Logs:
~/.streamtv/server.log
The installation script creates a macOS LaunchAgent. To use it:
# Load the service
launchctl load ~/Library/LaunchAgents/com.retro-tv-simulator.plist
# Unload the service
launchctl unload ~/Library/LaunchAgents/com.retro-tv-simulator.plist
# Check status
launchctl list | grep retro-tv-simulatorRun the uninstall script:
./uninstall_macos.shThis will:
- Stop the server
- Remove the service
- Remove installation files
- Optionally remove the database
If Python is not found after installation:
- Restart your terminal
- Check PATH:
echo $PATH - Verify installation:
/usr/local/bin/python3 --version
If FFmpeg is not found:
- Check if it's in PATH:
which ffmpeg - For user installation: Add
~/.local/binto PATH in~/.zshrc:export PATH="$HOME/.local/bin:$PATH"
- Restart terminal or run:
source ~/.zshrc
If port 8410 is already in use:
- Change port in
config.yaml:server: port: 8500
- Or stop the existing service:
launchctl unload ~/Library/LaunchAgents/com.retro-tv-simulator.plist
If you encounter issues with the virtual environment:
- Remove and recreate:
rm -rf ~/.retro-tv-simulator/venv python3 -m venv ~/.retro-tv-simulator/venv
- Reinstall dependencies:
source ~/.retro-tv-simulator/venv/bin/activate pip install -r requirements.txt
- macOS: 10.9 (Mavericks) or later
- Python: 3.8 or higher
- RAM: 2GB minimum, 4GB recommended
- Disk Space: 500MB for installation, additional space for media
- Apple Silicon (M1/M2/M3): Fully supported
- Intel Macs: Fully supported
After installation:
- Access the web interface: http://localhost:8410
- View API documentation: http://localhost:8410/docs
- Access IPTV playlist: http://localhost:8410/iptv/channels.m3u
- Add media items via API or web interface
- Configure schedules for your channels
For issues or questions:
- Check the main README
- Review API documentation
- Check installation guide
Welcome to the complete StreamTV documentation. This documentation is organized into three levels to accommodate users of all skill levels.
For Novice Users
- What is StreamTV?
- Basic concepts and terminology
- Simple setup and usage
- Common tasks step-by-step
- Basic troubleshooting
For Technicians
- Architecture overview
- Configuration details
- YAML file structure
- Channel and schedule management
- Advanced troubleshooting
- Script usage
🏗️ Expert Guide
For Engineers
- Complete system architecture
- Component interactions
- Code structure and patterns
- Advanced configuration
- Customization and extension
- Deep troubleshooting
- Installation Guide
- Quick Start Guide
- API Documentation
- HDHomeRun Integration
- Schedule System
- YAML Validation
- Troubleshooting Scripts
- Start with the Beginner Guide if you're new to StreamTV
- Check the Intermediate Guide for configuration and setup details
- Refer to the Expert Guide for deep technical information
- Use Troubleshooting Scripts for automated problem diagnosis
#
├── README.md (this file)
├── BEGINNER_GUIDE.md
├── INTERMEDIATE_GUIDE.md
├── EXPERT_GUIDE.md
├── TROUBLESHOOTING_SCRIPTS.md
├── INSTALLATION.md
├── QUICKSTART.md
├── API.md
├── HDHOMERUN.md
├── SCHEDULES.md
└── YAML_VALIDATION.md
Complete guide to all StreamTV documentation, organized by topic with descriptions.
New to StreamTV? Start here:
- Quick Start Guide - Get started in minutes
- QUICKSTART.md - Quick start overview
- Beginner Guide - For novice users
- Installation Guide - Detailed setup instructions
- README.md - Project overview, features, and documentation structure
- INDEX.md - This file - complete documentation index
- API.md - Complete API reference with endpoints, request/response formats, and examples
- TROUBLESHOOTING.md - Common issues, solutions, and diagnostic procedures
- YAML_VALIDATION.md - YAML file validation rules and schema documentation
- BEGINNER_GUIDE.md - Getting started guide for novice users with basic concepts and step-by-step instructions
- INTERMEDIATE_GUIDE.md - For technicians: architecture overview, configuration details, YAML structure, and advanced troubleshooting
- EXPERT_GUIDE.md - For engineers: complete system architecture, component interactions, code structure, and deep customization
Location: authentication/
- AUTHENTICATION.md - Basic authentication setup and usage guide for Archive.org and YouTube
- AUTHENTICATION_SYSTEM.md - Complete authentication system overview, web interface login, automatic re-authentication, and credential storage
- PASSKEY_AUTHENTICATION.md - Apple Passkey (WebAuthn) authentication guide for passwordless, biometric authentication using Face ID/Touch ID
- SCHEDULES.md - Creating and managing channel schedules, YAML format, and scheduling concepts
- HDHOMERUN.md - HDHomeRun emulation setup, Plex/Emby/Jellyfin integration, and tuner configuration
- COMPARISON.md - Feature comparisons with other IPTV solutions
Location: features/
-
AUTO_HEALER.md — optional AI-assisted recovery; production defaults
enabled: false,apply_fixes: false(advise / dry-run). Prefer in-tree heal scripts. - ERSATZTV_INTEGRATION.md - ErsatzTV integration guide and setup instructions
- ERSATZTV_COMPLETE_INTEGRATION.md - Complete ErsatzTV integration status, all integrated features, and compatibility confirmation
- Plex → plex/ - Complete Plex Media Server integration guides
- ErsatzTV → features/ERSATZTV_COMPLETE_INTEGRATION.md
Location: #
- TROUBLESHOOTING.md - Main troubleshooting guide with common issues and solutions (in parent directory)
- INSTALLATION_ISSUES.md - Installation and setup issues (Python, FFmpeg, ports, virtual environment)
- PLEX_INTEGRATION_ISSUES.md - Plex tuner discovery, channel mapping, EPG guide, and streaming issues
- STREAMING_ISSUES.md - Video streaming, playback, buffering, and format-specific issues
- FFMPEG_ISSUES.md - FFmpeg installation, codec errors, format issues, and performance
- NETWORK_ISSUES.md - DNS resolution, YouTube/Archive.org connectivity, timeouts, and network performance
- DATABASE_ISSUES.md - Database connection errors, corruption, locking, performance, and maintenance
- TROUBLESHOOTING_SCRIPTS.md - Interactive troubleshooting scripts documentation using SwiftDialog for automated diagnostics
- LOGGING.md - Logging configuration, log file locations, and log viewing tools
#
├── INDEX.md (this file)
├── README.md
│
├── Core Documentation (root level)
│ ├── API.md
---
#### QUICKSTART
# StreamTV Quick Start Guide
## Installation
1. **Install dependencies:**
```bash
pip install -r requirements.txt
-
Configure:
cp config.example.yaml config.yaml # Edit config.yaml if needed -
Run:
python -m streamtv.main
curl -X POST http://localhost:8410/api/channels \
-H "Content-Type: application/json" \
-d '{
"number": "1",
"name": "My YouTube Channel",
"group": "Entertainment"
}'curl -X POST http://localhost:8410/api/media \
-H "Content-Type: application/json" \
-d '{
"source": "youtube",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}'curl -X POST http://localhost:8410/api/playlists \
-H "Content-Type: application/json" \
-d '{
"name": "My Playlist",
"channel_id": 1
}'curl -X POST http://localhost:8410/api/playlists/1/items/1- M3U Playlist: http://localhost:8410/iptv/channels.m3u
- EPG: http://localhost:8410/iptv/xmltv.xml
- Channel Stream: http://localhost:8410/iptv/channel/1.m3u8
- Open VLC
- Go to Media → Open Network Stream
- Enter:
http://localhost:8410/iptv/channels.m3u - Click Play
- Install IPTV Simple Client addon
- Configure:
- M3U Playlist URL:
http://localhost:8410/iptv/channels.m3u - EPG URL:
http://localhost:8410/iptv/xmltv.xml
- M3U Playlist URL:
- Install xTeVe or similar IPTV proxy
- Configure with StreamTV endpoints
curl -X POST http://localhost:8410/api/media \
-H "Content-Type: application/json" \
-d '{
"source": "archive_org",
"url": "https://archive.org/details/identifier"
}'- Python 3.8 or higher
- pip (Python package manager)
- FFmpeg (optional, for advanced streaming features)
If you have the source code:
cd streamtvpython3 -m venv venvpip install -r requirements.txtCopy the example configuration:
cp config.example.yaml config.yamlEdit config.yaml with your settings:
server:
host: "0.0.0.0"
port: 8410
base_url: "http://localhost:8410"
database:
url: "sqlite:///./streamtv.db"
youtube:
enabled: true
quality: "best"
archive_org:
enabled: true
preferred_format: "h264"The database will be automatically initialized on first run.
python -m streamtv.mainOr using uvicorn directly:
uvicorn streamtv.main:app --host 0.0.0.0 --port 8410- Web Interface: http://localhost:8410
- API Documentation: http://localhost:8410/docs
- IPTV Playlist: http://localhost:8410/iptv/channels.m3u
- EPG: http://localhost:8410/iptv/xmltv.xml
All API endpoints are prefixed with /api unless otherwise noted.
If api_key_required is enabled in configuration, include the access token as a query parameter:
?access_token=YOUR_TOKEN
GET /api/channels
Returns a list of all channels.
Response:
[
{
"id": 1,
"number": "1",
"name": "My Channel",
"group": "Entertainment",
"enabled": true,
"logo_path": null,
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
]GET /api/channels/{channel_id}
GET /api/channels/number/{channel_number}
POST /api/channels
Content-Type: application/json
{
"number": "1",
"name": "My Channel",
"group": "Entertainment",
"enabled": true,
"logo_path": null
}
PUT /api/channels/{channel_id}
Content-Type: application/json
{
"name": "Updated Channel Name"
}
DELETE /api/channels/{channel_id}
GET /api/media?source=youtube&skip=0&limit=100
Query parameters:
-
source: Filter by source (youtube, archive_org) -
skip: Number of items to skip (pagination) -
limit: Maximum number of items to return
GET /api/media/{media_id}
---
#### TROUBLESHOOTING
# StreamTV Troubleshooting Guide
## Quick Diagnostics
Run these diagnostic scripts directly from this page to check your installation:
- [Run Script: check_python](script:check_python) - Check Python installation and version
- [Run Script: check_ffmpeg](script:check_ffmpeg) - Check FFmpeg installation and version
- [Run Script: check_database](script:check_database) - Check database connectivity and integrity
- [Run Script: check_ports](script:check_ports) - Check if required ports are available
- [Run Script: test_connectivity](script:test_connectivity) - Test network connectivity to media sources (with auto-fix for DNS issues)
- [Run Script: repair_database](script:repair_database) - Attempt to repair corrupted database
- [Run Script: clear_cache](script:clear_cache) - Clear application cache
**How to use:** Click on any script link above. You'll be prompted to confirm before the script runs. The results will appear below.
## Using the Web Interface for Troubleshooting
StreamTV includes powerful web-based troubleshooting tools accessible from the web interface:
### Streaming Logs & Self-Healing
1. **Access Streaming Logs**: Click "Streaming Logs" in the sidebar under Resources
2. **Real-Time Monitoring**: View logs as they happen with automatic updates
3. **Error Detection**: Errors and warnings are automatically highlighted and clickable
4. **Click for Details**: Click any error/warning to see:
- Full error context (20 lines before/after)
- Matched troubleshooting scripts
- **"Self-Heal" button** to automatically run fixes
5. **Auto-Fix Prompts**: When scripts detect fixable issues (e.g., missing yt-dlp, DNS issues), you'll be prompted to apply fixes automatically
### Interactive Documentation
All documentation is available directly in the web interface:
- Click **"Documentation"** in the sidebar dropdown
- Browse guides: Quick Start, Beginner, Installation, Path Independence, GUI Installer, SwiftUI Installer
- Click script buttons in documentation to run diagnostics
- Access troubleshooting guides from the **"Troubleshooting"** dropdown
### AI Troubleshooting Assistant
Install Ollama for AI-powered troubleshooting:
1. Click **"AI Troubleshooting"** in the sidebar under Resources
2. Install Ollama (~5 GB base installation)
3. Select and install AI models based on your hardware
4. The AI can analyze errors and suggest fixes based on your system's configuration
**Features**:
- Analyzes log errors and provides explanations
- Suggests fixes based on your system configuration
- Learns from patterns in your logs
- Completely private - no data leaves your machine
## Common Installation Issues
### Python Not Found
**Symptoms**: `python3: command not found` or Python version too old
**Solutions**:
1. **macOS**:
- Download from [python.org](https://www.python.org/downloads/)
- Or use Homebrew: `brew install python3`
- Run diagnostic: [Run Script: check_python](script:check_python)
3. **Linux**:
- Ubuntu/Debian: `sudo apt-get install python3 python3-pip`
- Fedora: `sudo dnf install python3 python3-pip`
- Arch: `sudo pacman -S python python-pip`
### FFmpeg Not Found
**Symptoms**: `ffmpeg: command not found` or FFmpeg errors in logs
**Solutions**:
1. **macOS**:
- Apple Silicon: Download from [evermeet.cx](https://evermeet.cx/ffmpeg/)
- Or use Homebrew: `brew install ffmpeg`
- Run diagnostic: [Run Script: check_ffmpeg](script:check_ffmpeg)
3. **Linux**:
- Ubuntu/Debian: `sudo apt-get install ffmpeg`
- Fedora: `sudo dnf install ffmpeg`
- Arch: `sudo pacman -S ffmpeg`
---
### Installation Documentation
#### GUI INSTALLER README
# StreamTV GUI Installer for macOS
## Overview
The GUI installer provides a user-friendly graphical interface for installing and updating StreamTV on macOS.
## Features
### Visual Status Indicators
Each module shows its status with color-coded indicators:
- **Green Checkmark (✓)**: Module installed/updated successfully
- **Yellow Warning (⚠)**: Module has issues but installation continued
- **Red Error (✗)**: Module installation failed
### Module Detection
The installer automatically detects:
- **Existing installations**: Checks if modules are already installed
- **Updates needed**: Identifies modules that need updating
- **Corrupted installations**: Detects and offers to fix corrupted modules
### Auto-Fix Capabilities
When issues are detected, the installer can:
- Recreate corrupted virtual environments
- Reinstall missing dependencies
- Fix configuration file issues
- Repair database corruption
## Requirements
- macOS 10.9 (Mavericks) or later
- Python 3.8 or higher (will be installed if missing)
- tkinter (included with Python)
## Installation
### Easy Installation (Double-Click Method)
**Option 1: SwiftUI Installer (Native macOS - Recommended)**
1. Build the SwiftUI installer first (see BUILD_SWIFTUI.md)
2. **Double-click** `Install-StreamTV-SwiftUI.command`
3. The native SwiftUI installer window will open
4. Click **"Start Installation"**
5. Wait for installation to complete
6. Click **"Fix Issues"** if any problems are detected (optional)
7. Click **"Close"** when done
**Option 2: Python GUI Installer (No Build Required)**
1. **Double-click** `Install-StreamTV.command`
2. The Python GUI installer window will open
3. Click **"Start Installation"**
4. Wait for installation to complete
5. Click **"Fix Issues"** if any problems are detected (optional)
6. Click **"Close"** when done
### Alternative Methods
- **SwiftUI**: `Install-StreamTV-SwiftUI.command` - Native macOS experience
- **Python GUI**: `Install-StreamTV.command` - Python-based GUI
- **Shell Script**: `./install-gui.sh` - Run from Terminal
- **Python Direct**: `python3 install_gui.py` - Direct Python execution
## What Gets Installed
The installer automatically:
- ✓ Checks for Python (opens installer if needed)
- ✓ Checks for FFmpeg (installs via Homebrew or direct download)
- ✓ Creates virtual environment
- ✓ Installs all Python packages
- ✓ Sets up configuration
- ✓ Initializes database
- ✓ Sets up workspace directories for your channels
- ✓ Creates launch scripts and launchd service
## Troubleshooting
### "tkinter not found"
---
#### INSTALL MACOS
# macOS Installation Guide
Complete installation guide for StreamTV on macOS.
## Quick Start
Run the automated installation script:
```bash
./install_macos.sh
This script will:
- Check and install Python 3.8+ from python.org
- Install FFmpeg from official sources (Homebrew as fallback)
- Set up a virtual environment
- Install all Python dependencies
- Configure the platform
- Initialize the database
- Create launch scripts
- Optionally start the server
If you prefer to install manually:
Download and install from python.org:
- Choose the macOS installer for your architecture (Intel or Apple Silicon)
- Run the installer and follow the instructions
- Verify installation:
python3 --version
For Apple Silicon Macs, download from evermeet.cx:
curl -L -o /tmp/ffmpeg.zip https://evermeet.cx/ffmpeg/ffmpeg-6.1.1.zip
unzip -q -o /tmp/ffmpeg.zip -d /tmp/
sudo mv /tmp/ffmpeg /usr/local/bin/ffmpeg
sudo chmod +x /usr/local/bin/ffmpegbrew install ffmpegpython3 -m venv ~/.retro-tv-simulator/venv
source ~/.retro-tv-simulator/venv/bin/activatepip install --upgrade pip setuptools wheel
pip install -r requirements.txtcp config.example.yaml config.yaml
# Edit config.yaml as neededpython3 -c "from streamtv.database.session import init_db; init_db()"Option A: Using Xcode (Recommended)
- Open
StreamTVInstaller/StreamTVInstaller.xcodeprojin Xcode - Select "My Mac" as destination
- Press
Cmd+Bto build - The app will be in
StreamTVInstaller/build/StreamTV Installer.app
Option B: Using Build Script
./build-installer.shDouble-Click Method:
- Double-click
Install-StreamTV-SwiftUI.command - The native SwiftUI installer will open
- Click "Start Installation"
Direct App Launch:
- Navigate to
StreamTVInstaller/build/StreamTV Installer.app - Double-click the app
- Native macOS Experience: Built with SwiftUI
- Beautiful Interface: Follows macOS design guidelines
- Smooth Animations: Native macOS animations
- Dark Mode: Automatic dark mode support
- Accessibility: Full VoiceOver support
Same as the Python installer:
- ✓ Python (opens installer if needed)
- ✓ FFmpeg (installs via Homebrew or direct download)
- ✓ Virtual environment
- ✓ Python dependencies
- ✓ Configuration
- ✓ Database
- ✓ Workspace directories ready for your channels
- ✓ Launch scripts
Install Xcode from the App Store, then:
xcode-select --install- Make sure Xcode is up to date
- Clean build:
rm -rf build/ - Rebuild in Xcode
Right-click → Open (to bypass Gatekeeper)
- Better Performance: Native SwiftUI is faster
- Modern UI: Follows macOS Human Interface Guidelines
- Better Integration: Works seamlessly with macOS
Option 1: SwiftUI Installer (Native macOS - Recommended)
- Build the installer first (see BUILD_SWIFTUI.md or use Xcode)
-
Double-click
Install-StreamTV-SwiftUI.command - The native SwiftUI installer window will open
- Click "Start Installation"
- Wait for installation to complete
- Click "Fix Issues" if any problems are detected (optional)
- Click "Close" when done
Option 2: Python GUI Installer (No Build Required)
-
Double-click
Install-StreamTV.command - The Python GUI installer window will open
- Click "Start Installation"
- Wait for installation to complete
- Click "Fix Issues" if any problems are detected (optional)
- Click "Close" when done
-
SwiftUI:
Install-StreamTV-SwiftUI.command- Native macOS experience (requires build) -
Python GUI:
Install-StreamTV.command- Python-based GUI (no build needed) -
Shell Script:
./install-gui.sh- Run from Terminal -
Command-Line:
./install_macos.sh- Traditional installer
The installer automatically:
- ✓ Checks for Python (opens installer if needed)
- ✓ Checks for FFmpeg (installs via Homebrew or direct download)
- ✓ Creates virtual environment
- ✓ Installs all Python packages
- ✓ Sets up configuration
- ✓ Initializes database
- ✓ Sets up workspace directories for your channels
- ✓ Creates launch scripts
- ✓ Optional: AI Troubleshooting Assistant (Ollama) - Prompts during installation
-
Start StreamTV: Run
~/.streamtv/start_server.shor./start_server.sh - Open Browser: Go to http://localhost:8410
-
Explore the Web Interface:
- Documentation: Click "Documentation" in the sidebar to access all guides
- Streaming Logs: Click "Streaming Logs" to view real-time logs and errors
- Self-Healing: Click on any error in the logs to see details and auto-fix options
- Enjoy: Your IPTV platform is ready!
All documentation is now available directly in the web interface:
- Click "Documentation" in the sidebar dropdown
- Browse guides: Quick Start, Beginner, Installation, Path Independence, GUI Installer, SwiftUI Installer
- Click script buttons in documentation to run diagnostics
- Access troubleshooting guides from the "Troubleshooting" dropdown
Monitor and fix issues automatically:
- Access: Click "Streaming Logs" in the Resources section
- Real-Time Monitoring: See logs as they happen (Server-Sent Events)
- Error Detection: Errors and warnings are automatically highlighted
-
Click for Details: Click any error/warning to see:
- Full error context (20 lines before/after)
- Matched troubleshooting scripts
- "Self-Heal" button to automatically run fixes
- Auto-Fix Prompts: When scripts detect fixable issues (e.g., missing yt-dlp, DNS issues), you'll be prompted to apply fixes automatically
Guides for installing and setting up StreamTV on macOS and other platforms.
Start here: QUICK_START.md
- QUICK_START.md - General quick start
- QUICK_START_SWIFTUI.md - SwiftUI installer
- INSTALL_MACOS.md - Automated macOS setup
- GUI_INSTALLER_README.md - GUI installer guide
- SWIFTUI_INSTALLER_README.md - SwiftUI installer details
- YOUTUBE_API_SETUP.md - YouTube Data API configuration
# Automated installer
./install_macos.sh
# OR SwiftUI GUI installer
./Install-StreamTV.commandStart Installing: QUICK_START.md
The SwiftUI installer provides a native macOS experience with a beautiful, modern interface built using Apple's SwiftUI framework.
- SwiftUI Interface: Built with Apple's modern UI framework
- Native Look & Feel: Matches macOS design guidelines
- Smooth Animations: Native macOS animations and transitions
- Accessibility: Full VoiceOver and accessibility support
- Dark Mode: Automatic dark mode support
Each module shows its status with native macOS icons:
- Green Checkmark: Module installed/updated successfully
- Yellow Warning: Module has issues but installation continued
- Red Error: Module installation failed
The installer automatically detects:
- Existing installations: Checks if modules are already installed
- Updates needed: Identifies modules that need updating
- Corrupted installations: Detects and offers to fix corrupted modules
When issues are detected, the installer can:
- Recreate corrupted virtual environments
- Reinstall missing dependencies
- Fix configuration file issues
- Repair database corruption
- Open
StreamTVInstaller/StreamTVInstaller.xcodeprojin Xcode - Select "My Mac" as the destination
- Press
Cmd+Bto build - Press
Cmd+Rto run - The app will be built in
StreamTVInstaller/build/StreamTV Installer.app
./build-installer.shThis will:
- Build the SwiftUI app
- Create a standalone
.appbundle - Place it in the
build/directory
cd StreamTVInstaller
swift build -c release- Build the installer (see above)
-
Double-click
Install-StreamTV-SwiftUI.command - The SwiftUI installer will open automatically
- Click "Start Installation"
- Wait for installation to complete
- Click "Fix Issues" if any problems are detected (optional)
StreamTV now integrates with the YouTube Data API v3 to improve reliability and resolve streaming issues. The API is used for:
- Video validation - Check if videos exist and are available before attempting to stream
- Metadata retrieval - Get accurate video information (title, description, thumbnails, etc.)
- Error prevention - Detect unavailable videos early to avoid unnecessary yt-dlp calls
- Better error messages - Provide clear feedback when videos are private, deleted, or unavailable
- Reduced Rate Limiting - API validation prevents unnecessary yt-dlp requests
- Better Error Handling - Know immediately if a video is unavailable
- Improved Reliability - Validate videos before attempting to stream
- Enhanced Metadata - Get accurate information from YouTube's official API
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the YouTube Data API v3:
- Navigate to "APIs & Services" > "Library"
- Search for "YouTube Data API v3"
- Click "Enable"
- Create credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "API Key"
- Copy your API key
- (Optional) Restrict the API key to YouTube Data API v3 for security
Add your API key to config.yaml:
youtube:
enabled: true
quality: "best"
extract_audio: false
cookies_file: null
use_authentication: false
api_key: "YOUR_API_KEY_HERE" # Add your API key
oauth_client_id: null
oauth_client_secret: null
oauth_refresh_token: nullRestart the StreamTV server for changes to take effect.
- Video Validation: When a YouTube URL is requested, StreamTV first validates it using the YouTube Data API
- Availability Check: The API checks if the video is public and available
- Metadata Retrieval: If available, metadata is retrieved from the API (faster and more reliable)
- Stream URL Extraction: yt-dlp is still used to get the actual streaming URL (API doesn't provide this)
- Error Prevention: Unavailable videos are detected early, preventing unnecessary processing
If no API key is configured, StreamTV falls back to the previous behavior:
- Uses yt-dlp for all operations
- No pre-validation
- May encounter more rate limiting issues
The YouTube Data API v3 has a default quota of 10,000 units per day. Each API call consumes units:
-
videos.list(get video info): 1 unit -
search.list(search videos): 100 units
For most use cases, the default quota is sufficient. If you need more:
Common database-related issues and their solutions.
Database connection failedSQLite errordatabase is locked- Server won't start
-
Run database diagnostic:
- Use web interface: Run
check_databasescript - Verifies database connectivity
- Checks database integrity
- Use web interface: Run
-
Check database file permissions:
ls -la streamtv.db chmod 644 streamtv.db # If needed -
Check if database is locked:
# macOS/Linux lsof streamtv.dbIf locked, stop all StreamTV processes and try again.
-
Verify database location:
- Check
config.yamlfor database path - Default:
sqlite:///./streamtv.db - Ensure directory is writable
- Check
-
Test database connection:
python3 -c "from streamtv.database.session import SessionLocal; db = SessionLocal(); print('OK'); db.close()"
database disk image is malformed- Inconsistent data
- Queries fail unexpectedly
- Data appears corrupted
-
Backup current database:
cp streamtv.db streamtv.db.backup
-
Run repair script:
- Use web interface: Run
repair_databasescript - Attempts to repair corrupted database
- May recover some data
- Use web interface: Run
-
If repair fails:
# Restore from backup cp streamtv.db.backup streamtv.db # OR recreate database rm streamtv.db python3 -c "from streamtv.database.session import init_db; init_db()"
-
Re-import data:
- After recreating, re-import channels
- Re-import media items
- Recreate schedules
Common FFmpeg-related issues and their solutions.
ffmpeg: command not found- FFmpeg errors in logs
- Streaming fails immediately
-
Verify FFmpeg installation:
which ffmpeg ffmpeg -version
-
Install FFmpeg:
- See Installation Issues for platform-specific instructions
- Run diagnostic:
check_ffmpegscript
-
Configure FFmpeg path:
ffmpeg: ffmpeg_path: "/usr/local/bin/ffmpeg" # Custom path if needed
- "Codec not found" errors
- "Unsupported codec" messages
- Format not supported errors
-
Check codec support:
ffmpeg -codecs | grep h264 ffmpeg -codecs | grep aac ffmpeg -codecs | grep mp2
-
Update FFmpeg:
- Newer versions have better codec support
- Install latest version for your platform
-
Verify required codecs:
- H.264 (video) - Required
- AAC or MP2 (audio) - Required
- MPEG-2 (for HDHomeRun output) - Required
-
Check build configuration:
ffmpeg -buildconf
Look for required codecs in configuration.
- "Error opening input" for specific formats
- "Invalid data found" errors
- Format not recognized
-
Check format support:
ffmpeg -formats | grep mp4 ffmpeg -formats | grep avi
-
Test source file:
ffmpeg -i source_url -t 1 -f null -
This tests if FFmpeg can read the source.
Common issues encountered during StreamTV installation and their solutions.
Symptoms:
python3: command not found-
Python version too olderror - Installation script fails at Python check
Solutions:
macOS:
-
Download Python from python.org
- Choose the macOS installer for your architecture (Intel or Apple Silicon)
- Run the installer and follow instructions
- Verify:
python3 --version(should show 3.8+)
-
Or use Homebrew:
brew install python3
-
Run diagnostic: Use the web interface to run
check_pythonscript
Linux:
- Ubuntu/Debian:
sudo apt-get install python3 python3-pip - Fedora:
sudo dnf install python3 python3-pip - Arch:
sudo pacman -S python python-pip
Symptoms:
- Error: "Python 3.8+ required"
- Current version is 3.7 or earlier
Solutions:
- Upgrade Python to 3.8 or later
- Verify version:
python3 --version - If multiple Python versions installed, ensure
python3points to 3.8+
Symptoms:
ffmpeg: command not found- FFmpeg errors in logs
- Streaming fails with codec errors
Solutions:
macOS:
-
Apple Silicon (M1/M2/M3): Download from evermeet.cx
curl -L -o /tmp/ffmpeg.zip https://evermeet.cx/ffmpeg/ffmpeg-6.1.1.zip unzip -q -o /tmp/ffmpeg.zip -d /tmp/ sudo mv /tmp/ffmpeg /usr/local/bin/ffmpeg sudo chmod +x /usr/local/bin/ffmpeg
-
Homebrew (works for both Intel and Apple Silicon):
brew install ffmpeg
-
Run diagnostic: Use web interface to run
check_ffmpegscript
[Errno 8] nodename nor servname provided, or not knownUnable to resolve hostname- YouTube/Archive.org URLs fail to resolve
-
Run connectivity diagnostic:
- Use web interface: Run
test_connectivityscript - Automatically detects DNS issues
- Provides auto-fix options
- Use web interface: Run
-
Flush DNS cache:
macOS:
sudo dscacheutil -flushcache sudo killall -HUP mDNSResponder
Linux:
sudo systemd-resolve --flush-caches # systemd # OR sudo service network-manager restart # NetworkManager
ipconfig /flushdns -
Check DNS servers:
- Verify DNS server settings
- Try using Google DNS (8.8.8.8, 8.8.4.4)
- Test DNS resolution:
nslookup youtube.com
-
Test connectivity:
ping youtube.com ping archive.org curl https://www.google.com
-
Auto-fix via web interface:
- Run
test_connectivityscript - If DNS issues detected, auto-fix option appears
- Click to apply DNS cache flush (requires password)
- Run
-
yt-dlp not installederrors Unable to download API page- YouTube videos won't play
- Connection timeouts
-
Install/update yt-dlp:
pip install yt-dlp # OR update pip install --upgrade yt-dlpAuto-fix available via web interface if detected.
-
Check YouTube accessibility:
- Test in browser: https://www.youtube.com
- Verify YouTube is accessible
- Check for regional restrictions
-
Test connectivity:
- Run
test_connectivityscript
- Run
Common issues when integrating StreamTV with Plex Media Server.
- Plex shows "No tuners found"
- Discovery URL doesn't work
- HDHomeRun device not appearing in Plex
-
Verify StreamTV is running:
curl http://localhost:8410/hdhomerun/discover.json
Should return JSON with device information.
-
Check discovery URL:
- Use your server's IP address, not
localhost - Format:
http://YOUR_IP:8410/hdhomerun/discover.json - Example:
http://192.168.1.100:8410/hdhomerun/discover.json
- Use your server's IP address, not
-
Verify SSDP is enabled:
hdhomerun: enabled: true enable_ssdp: true # Must be true for auto-discovery
-
Check firewall:
- Port 8410 must be accessible
- Port 1900 (SSDP) must be open if using auto-discovery
- Test:
telnet YOUR_IP 8410
-
Manual tuner addition:
- Plex → Settings → Live TV & DVR
- Add Tuner → Manual
- Enter:
http://YOUR_IP:8410/hdhomerun/discover.json
- Tuner found but no channels listed
- Channel scan shows 0 channels
- Channels exist in StreamTV but not in Plex
-
Verify channels exist:
curl http://localhost:8410/api/channels
Should return list of channels.
-
Check channel lineup:
curl http://localhost:8410/hdhomerun/lineup.json
Should return channel lineup.
-
Rescan channels in Plex:
- Plex → Settings → Live TV & DVR
- Click "Refresh Guide" or "Scan for Channels"
- Wait for scan to complete
-
Verify channel numbers:
- Channels must have valid numbers (e.g., "1", "2", "80")
- Check in StreamTV web interface: http://localhost:8410/channels
-
Check channel enablement:
- Ensure channels are enabled in StreamTV
- Disabled channels won't appear in Plex
- Plex shows "Error tuning channel" for all channels
- Channels appear but won't play
Common issues with video streaming and playback in StreamTV.
- Channel exists but shows "No stream available"
- Timeout errors when trying to play
- "Stream not found" message
-
Verify channel is enabled:
- Check in web interface: http://localhost:8410/channels
- Ensure channel has
enabled: true - Disabled channels won't stream
-
Check channel has content:
- Channel must have media items or schedule
- Verify in web interface
- Check schedule file exists if using schedules
-
Verify schedule configuration:
- Check schedule file in
schedules/directory - Ensure schedule is linked to channel
- Validate schedule YAML syntax
- Check schedule file in
-
Test stream URL directly:
# Prefer HDHomeRun tune or soft-restart (dead route removed): curl -o /dev/null -w '%{http_code} %{size_download}\n' 'http://127.0.0.1:8410/auto/v{channel_number}' curl -X POST 'http://127.0.0.1:8410/api/channels/by-number/{channel_number}/stream-restart'
Or use channel number:
curl http://localhost:8410/hdhomerun/auto/v{channel_number} -
Check streaming logs:
- Access: http://localhost:8410/logs
- Look for errors when accessing channel
- Check FFmpeg errors
-
Verify streaming mode:
- CONTINUOUS: Requires schedule file
- ON_DEMAND: Can work with just media items
- Check channel configuration
- Video plays but buffers frequently
- Stuttering or choppy playback
- Long delays before playback starts
-
Check network bandwidth:
- Test connection speed
- Ensure sufficient bandwidth for streaming
- Check for network congestion
-
Reduce stream quality:
youtube: quality: "medium" # Instead of "best"
Or in channel settings via web interface.
-
Check FFmpeg performance:
- Monitor CPU usage during streaming
- Check FFmpeg processes:
ps aux | grep ffmpeg - Consider hardware acceleration if available
-
Adjust buffer settings:
streaming: buffer_size: 16384 # Increase buffer chunk_size: 2048 # Increase chunk size
StreamTV includes interactive troubleshooting scripts that use SwiftDialog to help diagnose and resolve issues. These scripts provide a user-friendly interface for common problems.
The troubleshooting scripts require SwiftDialog, a macOS dialog tool.
Install via Homebrew:
brew install --cask swiftdialogManual Installation:
- Download from: https://github.com/swiftDialog/swiftDialog/releases
- Install the
.pkgfile - Verify installation:
dialog --version
Location: scripts/troubleshoot_streamtv.sh
Purpose: Comprehensive troubleshooting for all StreamTV issues
Usage:
cd "/path/to/StreamTV"
./scripts/troubleshoot_streamtv.shFeatures:
- Server status checking
- Channel issue diagnosis
- Streaming problem resolution
- Plex integration help
- Database troubleshooting
- Configuration validation
- Log viewing
Menu Options:
-
Server Status
- Checks if StreamTV server is running
- Tests server connectivity
- Option to start server if not running
-
Channel Issues
- Channel won't play
- Channel starts from beginning
- Channel has no content
- Channel import failed
- Other channel issues
-
Streaming Issues
- Video won't play
- Video keeps buffering
- FFmpeg errors
- Stream stops after first video
- Other streaming issues
-
Plex Integration
- Plex can't find tuner
- Channels not appearing
- Stream won't play
- Guide not loading
- Other Plex issues
-
Database Issues
- Database integrity checks
- Backup database
- Reset database
- View database info
-
Configuration Issues
- Validate configuration
- View configuration
StreamTV includes comprehensive authentication support for both Archive.org and YouTube using a web-based interface.
The authentication system provides:
- Web interface login pages for both services
- Automatic credential storage in macOS Keychain (Archive.org)
- Automatic re-authentication when sessions expire
- Secure credential management with proper storage and handling
Access: Settings → Archive.org (in sidebar) or /api/auth/archive-org
Features:
- Login form with username and password fields
- Shows current authentication status
- Logout button to remove credentials
- Automatic credential storage in Keychain (on macOS)
- Checks authentication status on server startup
- Re-prompts via SwiftDialog if authentication fails
- Automatically re-authenticates when accessing restricted content
- Handles session expiration gracefully
-
GET /api/auth/archive-org- Login page -
POST /api/auth/archive-org- Login with credentials -
DELETE /api/auth/archive-org- Logout -
GET /api/auth/archive-org/status- Check authentication status
Access: Settings → YouTube (in sidebar) or /api/auth/youtube
Features:
- Upload cookies file (cookies.txt format)
- Shows current authentication status
- Instructions for exporting cookies
- Remove authentication button
How to Export Cookies:
- Install browser extension:
- Chrome/Edge: "Get cookies.txt LOCALLY"
- Firefox: "cookies.txt"
- Visit youtube.com and login
- Click extension icon
- Export cookies to cookies.txt file
- Upload file via web interface
StreamTV supports authentication with Archive.org to access restricted content that requires a login.
To enable Archive.org authentication, edit your config.yaml:
archive_org:
enabled: true
preferred_format: "h264"
username: "your_username" # Your Archive.org username
password: "your_password" # Your Archive.org password
use_authentication: true # Enable authentication-
Never commit credentials: Make sure
config.yamlis in.gitignore(it already is) - Use environment variables: For production, consider using environment variables instead of storing passwords in config files
-
File permissions: Ensure
config.yamlhas restricted permissions (e.g.,chmod 600 config.yaml)
- Initial Login: When authentication is enabled, StreamTV will automatically log in to Archive.org on first use
- Session Management: The adapter maintains session cookies for authenticated requests
- Automatic Re-authentication: If a session expires, StreamTV will automatically attempt to re-authenticate
- Transparent Usage: Once configured, authentication works transparently - all Archive.org requests will use authenticated sessions
You can test if authentication is working by:
- Adding a restricted Archive.org item:
curl -X POST http://localhost:8410/api/media \
-H "Content-Type: application/json" \
-d '{
"source": "archive_org",
"url": "https://archive.org/details/RESTRICTED_ITEM_IDENTIFIER"
}'- If authentication is working, you should be able to access the item. If not, you'll get a permission error.
Symptoms: Logs show "Archive.org login failed" or "Invalid credentials"
Solutions:
- Verify your username and password are correct
- Check that
use_authenticationis set totrue - Ensure Archive.org account is active and not locked
- Check network connectivity to Archive.org
StreamTV now supports Apple Passkey (WebAuthn) authentication as a security layer for YouTube OAuth login, providing passwordless, biometric authentication.
Apple Passkeys use WebAuthn technology to provide secure, passwordless authentication using:
- Face ID (iPhone/iPad with Face ID)
- Touch ID (MacBook with Touch ID)
- Device Passcode (fallback authentication)
Passkeys are stored securely in iCloud Keychain and sync across your Apple devices.
-
User initiates YouTube OAuth
- User clicks "Start OAuth with Passkey" on YouTube auth page
- System checks if Passkey is registered
-
Passkey Verification
- If registered: User authenticates with Face ID/Touch ID
- If not registered: User creates a new Passkey first
- Passkey verification confirms user identity
-
Google OAuth
- After Passkey verification, user is redirected to Google OAuth
- User authorizes StreamTV to access YouTube
- OAuth tokens are stored securely
- Phishing Resistant: Passkeys use public-key cryptography
- No Passwords: Eliminates password-related security risks
- Biometric Security: Uses device biometrics (Face ID/Touch ID)
- Device Bound: Passkeys are tied to specific devices
- Private: Biometric data never leaves your device
-
Install webauthn library:
pip install webauthn
-
Compatible Browser:
- Safari 16+ (macOS/iOS) - Full Passkey support
-
Device Requirements:
- macOS: Touch ID or device passcode
- iOS/iPadOS: Face ID, Touch ID, or device passcode
StreamTV includes an intelligent auto-healing system that automatically monitors logs, detects errors, and applies fixes using AI-powered analysis.
🤖 AI-Powered Analysis: Uses Ollama AI to analyze errors and suggest fixes 📊 Pattern Detection: Identifies recurring error patterns automatically 🔧 Automatic Fixes: Applies known fixes for common issues 📈 Trend Analysis: Tracks error trends over time 💾 Safe Backups: Creates backups before applying any fixes 🔄 Continuous Monitoring: Can run continuously to keep your system healthy
The auto-healer uses Ollama for AI-powered log analysis.
-
Install Ollama:
# macOS brew install ollama # Linux curl -fsSL https://ollama.ai/install.sh | sh
-
Start Ollama service:
ollama serve
-
Pull the model (recommended: llama3.2):
ollama pull llama3.2:latest
The auto-healer uses standard StreamTV dependencies (httpx, pyyaml, etc.) which are already installed.
Edit config.yaml to configure auto-healing:
auto_healer:
enabled: false # Set to true to enable
enable_ai: true # Use AI for analysis
ollama_url: http://localhost:11434
ollama_model: llama3.2:latest
check_interval: 30 # Minutes between checks
apply_fixes: false # true = auto-apply, false = dry-run
max_fix_attempts: 3 # Max attempts per errorThis document confirms that all ErsatzTV-compatible features are fully integrated and operational in the StreamTV platform.
All ErsatzTV scheduling features have been successfully integrated and are actively used throughout the platform.
Status: ✅ Fully Integrated
Features:
- ✅ YAML import support (
importdirective) - ✅ Reset instructions support (
resetsection) - ✅ Content definitions parsing
- ✅ Sequence parsing
- ✅ Playout instructions parsing
- ✅ Base directory resolution for imports
- ✅ Recursive import processing
Usage:
from streamtv.scheduling import ScheduleParser
schedule = ScheduleParser.parse_file(
Path("schedules/mn-olympics-1980.yml"),
base_dir=Path("schedules")
)Status: ✅ Fully Integrated
ErsatzTV Handlers Implemented:
- ✅
padToNext- Pad to next time boundary (hour/half-hour) - ✅
padUntil- Pad until specific time - ✅
waitUntil- Wait until specific time - ✅
skipItems- Skip items from collections - ✅
shuffleSequence- Shuffle sequence items
Additional Features:
- ✅ Seeded random number generation (for consistency)
- ✅ Pre-roll, mid-roll, post-roll sequence support
- ✅ Duration-based filler with 10% tolerance
- ✅ Custom titles support
- ✅ Continuous playback generation
- ✅ Repeat logic
Usage:
from streamtv.scheduling import ScheduleEngine
engine = ScheduleEngine(db, seed=12345)
playlist_items = engine.generate_playlist_from_schedule(
channel, schedule, max_items=1000
)
---
#### ERSATZTV INTEGRATION
# ErsatzTV Integration - Enhanced Scheduling Features
This document describes the ErsatzTV-compatible features that have been integrated into the StreamTV platform.
## Overview
The platform now supports advanced scheduling features inspired by [ErsatzTV](https://github.com/ErsatzTV/ErsatzTV), allowing for more sophisticated channel programming while maintaining compatibility with direct streaming from YouTube and Archive.org.
## New Features
### 1. YAML Import Support
Schedule files can now import other YAML files to share common content definitions and sequences:
```yaml
import:
- common-commercials.yml
- shared-sequences.yml
content:
- key: my_content
collection: My Collection
order: chronologicalHow it works:
- Imported files are processed first
- Content and sequences are merged (existing keys take precedence)
- Supports relative and absolute paths
- Imports are processed recursively
Pads the schedule to the next hour or half-hour boundary:
sequence:
- key: my-sequence
items:
- padToNext: 30 # Pad to next 30-minute boundary
content: filler_collection
fallback: backup_filler
filler_kind: CommercialParameters:
-
padToNext: Minutes to pad to (e.g., 30 for half-hour, 60 for hour) -
content: Primary content collection to use for padding -
fallback: Fallback collection if primary is insufficient -
filler_kind: Type of filler (Commercial, Filler, etc.) -
trim: Whether to trim items to fit exactly -
discard_attempts: Number of items to skip if too long
Pads the schedule until a specific time:
---
### Plex Documentation
#### PLEX API SCHEDULE INTEGRATION COMPLETE
# ✅ Plex API Schedule Integration - Complete!
## Status: Full Integration Active
Your Plex API integration for schedules and EPG has been successfully completed and is now active!
### ✅ Updated Configuration
```yaml
plex:
enabled: true
base_url: "http://localhost:32400"
token: "HeyD3N9rKrtJDsRNL6-n" ✅ Updated and active
use_for_epg: true ✅ Enabled for schedule integration-
Plex Token Updated
- ✅ New token:
HeyD3N9rKrtJDsRNL6-n - ✅ Token saved to config.yaml
- ✅ Configuration verified
- ✅ New token:
-
Active Plex API Integration
- ✅ Plex API client initialized during EPG generation
- ✅ Authentication with your Plex token
- ✅ DVR detection for channel mapping
- ✅ Schedule enhancement active
-
EPG Generation Enhancements
- ✅ Plex-compatible XMLTV format
- ✅ Channel mapping from Plex DVR (when available)
- ✅ Enhanced metadata integration
- ✅ Proper async client management
The EPG generation process now:
-
Initializes Plex API Client
- Connects to: http://localhost:32400 - Authenticates with token: HeyD3N9rKrtJDsRNL6-n - Logs successful connection -
Detects Plex DVRs
- Queries Plex for configured DVRs - Maps channels between StreamTV and Plex - Enhances channel metadata -
Generates Enhanced EPG
- Creates Plex-compatible XMLTV - Includes schedule data from StreamTV channels - Adds Plex metadata when available - Proper cleanup after generation
After adding a new channel (e.g., Channel 80 - Magnum P.I.), rescanning with Plex tuner doesn't show the new channel.
Plex caches the HDHomeRun channel lineup and doesn't always refresh it properly during a rescan.
Channel 80 IS in the HDHomeRun lineup:
{
"GuideNumber": "80",
"GuideName": "Magnum P.I. Complete Series",
"URL": "http://localhost:8410/hdhomerun/auto/v80",
"HD": 0
}The channel is properly configured and exposed. Plex just needs to refresh its cache.
This forces Plex to completely refresh the lineup:
-
Open Plex Web Interface (http://100.70.119.112:32400/web)
-
Go to Settings → Live TV & DVR
-
Find your StreamTV HDHomeRun device
-
Click the "..." menu → Remove Device
-
Wait 10 seconds
-
Click "Add DVR Source" → Select Network Device
-
Plex should auto-discover:
StreamTV HDHomeRun (FFFFFFFF) -
Click Continue and follow the setup
-
All 6 channels should now appear (1980, 1984, 1988, 1992, 1994, 80)
Sometimes Plex needs a restart to refresh the lineup:
# On your Plex server machine
sudo systemctl restart plexmediaserver
---
#### PLEX CONNECTION FIX
# Plex Connection Test - Fix Applied ✅
## Issue Resolved
The Plex connection test was showing an error, but the connection is now working correctly after fixing the API client configuration.
### What Was Fixed
1. **Accept Header**: Changed from `application/json` to `application/xml` (Plex returns XML by default)
2. **Error Handling**: Improved error messages to provide specific diagnostics
3. **XML Parsing**: Added BOM handling for XML response parsing
### Connection Test Results
✅ **Connection Successful!**
- Server: Home PLEX
- Version: 1.42.2.10156-f737b826c
- URL: http://100.70.119.112:32400
- Token: Configured (20 characters)
### Current Configuration
```yaml
plex:
enabled: true
base_url: http://100.70.119.112:32400
token: HeyD3N9rKrtJDsRNL6-n
use_for_epg: true- Refresh the Page: The error message might be from a previous test
- Click "Test Connection" Again: The improved error handling should now work
-
Check Server Logs: Look at
streamtv.logfor detailed error messages
The connection test now provides specific error messages:
- ✅ Authentication errors: "Authentication failed. Plex token is invalid or expired."
- ✅ Connection errors: "Could not connect to [URL]. Check if server is running..."
- ✅ Timeout errors: "Connection timed out. Server may be unreachable..."
- ✅ HTTP errors: Shows specific status codes and error details
You can test the connection manually:
# Test Plex server directly
curl "http://100.70.119.112:32400/" \
-H "X-Plex-Token: HeyD3N9rKrtJDsRNL6-n"
# Test via StreamTV API
curl -X POST http://localhost:8410/api/settings/plex/test- Refresh the Settings Page: Clear any cached error messages
StreamTV now integrates with the Plex Media Server API to enhance EPG (Electronic Program Guide) generation and ensure full compatibility with Plex DVR functionality.
- Plex-Compatible XMLTV Format - Ensures EPG data works seamlessly with Plex
- Enhanced Metadata - Uses Plex API for channel mapping and validation
- Better Channel Information - Leverages Plex's EPG data when available
- DVR Integration - Compatible with Plex DVR functionality
- Open Plex Media Server web interface
- Go to Settings → Network
- Enable "Show Advanced" if needed
- Find your Plex token in the URL or use the API:
# Get token from Plex server curl -X GET "http://YOUR_PLEX_SERVER:32400/api/v2/resources?includeHttps=1&X-Plex-Token=YOUR_TOKEN"
Alternatively, you can find your token in:
- Browser developer tools (Network tab) when accessing Plex
- Plex server logs
- Using Plex authentication flow
Add Plex configuration to config.yaml:
plex:
enabled: true
base_url: "http://192.168.1.100:32400" # Your Plex server URL
token: "your-plex-token-here" # Your Plex authentication token
use_for_epg: true # Enable EPG enhancement via Plex APIRestart the server for changes to take effect.
- Channel Validation: Plex API validates channel mappings
- Metadata Enhancement: Uses Plex EPG data when available
- Format Compliance: Ensures XMLTV output is fully Plex-compatible
- Channel Mapping: Maps StreamTV channels to Plex EPG channels
StreamTV generates standard XMLTV format that is compatible with Plex, but without Plex-specific enhancements.
Your Plex authentication token has been successfully integrated into StreamTV!
plex:
enabled: true
base_url: "http://localhost:32400"
token: "HeyD3N9rKrtJDsRNL6" ✅ Configured
use_for_epg: true-
Token Added: Plex token has been saved to
config.yaml - Configuration Verified: Settings load successfully
- EPG Enhancements Active: All Plex-compatible features are enabled
If you're seeing authentication errors, the token might need to be:
-
Longer: Plex tokens are typically 20+ characters
- Your current token:
HeyD3N9rKrtJDsRNL6(16 characters) - Typical Plex tokens are longer alphanumeric strings
- Your current token:
-
Full Token: Make sure you copied the complete token from:
- Browser Developer Tools → Network → Request Headers →
X-Plex-Token - Should be a long string like:
abcdefghijklmnopqrstuvwxyz1234567890
- Browser Developer Tools → Network → Request Headers →
-
Alternative: If the token is incomplete, you can:
- Get the full token again using:
python3 scripts/get_plex_token.py - Or check browser console:
window.localStorage.getItem('token')
- Get the full token again using:
Even if the Plex API connection needs the full token, all EPG enhancements are active:
✅ Plex-Compatible XMLTV Format
- Proper channel IDs
- Multiple display names
- Absolute URLs for logos/thumbnails
- Language attributes on all fields
✅ Enhanced Metadata
- Required fields always included
- Standard XMLTV format
- At least one programme per channel
✅ DVR Compatibility
- Works seamlessly with Plex DVR
- Proper time formatting
- Valid XML structure
Your Plex API integration for schedules/EPG has been successfully configured and activated!
plex:
enabled: true
base_url: "http://localhost:32400"
token: "HeyD3N9rKrtJDsRNL6-n" ✅ Updated and configured
use_for_epg: true ✅ Active for schedule integration-
Plex API Client Integration
- ✅ Client initialized during EPG generation
- ✅ Authentication with your Plex token
- ✅ DVR detection and channel mapping support
-
Schedule/EPG Enhancement
- ✅ Active use of Plex API during EPG generation
- ✅ Channel mapping from Plex DVR (if configured)
- ✅ Enhanced metadata from Plex sources
-
Plex-Compatible Format
- ✅ XMLTV format optimized for Plex
- ✅ Proper channel IDs and display names
- ✅ Absolute URLs for media assets
- ✅ Language attributes on all fields
The EPG generation now:
-
Initializes Plex API Client
- Connects to your Plex server at
http://localhost:32400 - Authenticates using your token
- Logs successful connection
- Connects to your Plex server at
-
Enhances Channel Mapping
- Detects configured Plex DVRs
- Maps channels between StreamTV and Plex
- Enhances channel metadata
-
Generates EPG
- Creates Plex-compatible XMLTV format
- Includes all schedule data from your channels
- Adds enhanced metadata from Plex when available
- ✅ Plex API Connection: Active during EPG generation
- ✅ DVR Detection: Automatically detects Plex DVRs
- ✅ Channel Mapping: Maps StreamTV channels to Plex EPG
- ✅ Metadata Enhancement: Uses Plex data when available
Your Plex API integration has been configured with:
✅ Enabled: true
✅ Base URL: http://localhost:32400 (detected automatically)
✅ EPG Enhancement: true
⏳ Token: Needs to be configured (see below)
To complete the setup, you need to add your Plex authentication token.
Run this helper script:
python3 scripts/get_plex_token.pyThis will:
- Open your Plex Web App in a browser
- Show detailed instructions
- Guide you through extracting the token
-
Open Plex Web App:
-
Open Browser Developer Tools:
- macOS:
Cmd + Option + I
- macOS:
-
Go to Network Tab
-
Refresh the page
-
Find a request and check:
- Request Headers
- Look for
X-Plex-Tokenparameter - Copy the token value
- Open Developer Tools → Console tab
- Type:
window.localStorage.getItem('token') - Press Enter
- Copy the returned value
Once you have your token, update config.yaml:
plex:
enabled: true
---
## Additional Resources
- [Full Documentation Index](/Users/roto1231/Documents/XCode Projects/StreamTV/StreamTV-macOS/docs/INDEX.md)
- [API Reference](/Users/roto1231/Documents/XCode Projects/StreamTV/StreamTV-macOS/docs/API.md)
- [Troubleshooting Guide](/Users/roto1231/Documents/XCode Projects/StreamTV/StreamTV-macOS/docs/TROUBLESHOOTING.md)