Installation Guide

Complete installation documentation for all platforms.

Quick Start

StreamTV Quick Start Guide for macOS

🚀 Easy Installation (Double-Click Method)

For macOS Users

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

Alternative Methods

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

📋 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
✓ Creates default channels
✓ Creates launch scripts
✓ Optional: AI Troubleshooting Assistant (Ollama) - Prompts during installation

🎯 After Installation

Start StreamTV: Run ~/.streamtv/start_server.sh or ./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!

🆕 New Features

Interactive Documentation

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

Streaming Logs & Self-Healing

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

AI-Powered Troubleshooting Assistant

During installation, you'll be prompted to optionally install Ollama for AI-powered troubleshooting:

What is it?: An AI assistant that analyzes errors and suggests fixes
Storage: ~9 GB total (Ollama base + AI model)
Cost: 100% free - runs entirely on your Mac
Models: The installer scans your hardware and shows available models
Recommended: Mistral 7B (~4GB) - best balance of quality and size
Skip: You can skip this and install later if desired

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 Mac

Interactive Troubleshooting

Run diagnostic scripts directly from the web interface:

From Documentation: Click script buttons (e.g., "Run Script: test_connectivity")
From Logs: Click "Self-Heal" on error detail pages
Available Scripts:
- Network diagnostics (with DNS auto-fix for macOS)
- Python/FFmpeg verification
- Database integrity checks
- Port availability checks

❓ Troubleshooting

"tkinter not found"

On macOS, tkinter should be included with Python
If missing, reinstall Python from python.org

"Python not found"

The installer will download and open Python installer automatically
After installation, run the installer again

"FFmpeg not found"

The installer will try Homebrew first
Then direct download for Apple Silicon
Or provide manual installation instructions

"Permission denied"

Make files executable:

chmod +x Install-StreamTV.command
chmod +x install-gui.sh

GUI Doesn't Open

Make sure you're not running via SSH
Check Python and tkinter are installed
Try running from Terminal: ./install-gui.sh

📚 More Information

See README.md for full documentation
See GUI_INSTALLER_README.md for detailed GUI installer info
See PATH_INDEPENDENCE.md for path independence details

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)

Build the SwiftUI installer first (see BUILD_SWIFTUI.md)
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

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
✓ Creates default channels
✓ Creates launch scripts and launchd service

Troubleshooting

"tkinter not found"

On macOS, tkinter should be included with Python. If you see this error:

Reinstall Python from python.org (not Homebrew Python)
Or install tkinter separately (rarely needed)

"Python not found"

The installer will:

Download Python installer automatically
Open the installer for you
After installation, run the installer again

"FFmpeg not found"

The installer will try:

Homebrew installation (if Homebrew is installed)
Direct download for Apple Silicon
Manual installation instructions if both fail

Permission Errors

If you see permission errors:

Make files executable: chmod +x Install-StreamTV.command
For system-wide installation, you may need to run with sudo (not recommended)

GUI Doesn't Open

If the GUI doesn't open:

Make sure you're not running via SSH
Check that Python and tkinter are installed
Try running from Terminal: ./install-gui.sh
Check Console.app for error messages

After Installation

Once installation is complete:

Start StreamTV using ~/.streamtv/start_server.sh
Or run: ./start_server.sh (if in StreamTV directory)
Access the web interface at: http://localhost:8410
Enjoy your IPTV streaming platform!

Command-Line Alternative

If you prefer command-line installation:

./install_macos.sh

Path Independence

The installer works from any location:

Move it to any folder
Run from USB drive
Create shortcuts anywhere
Works even if symlinked

See PATH_INDEPENDENCE.md for details.

INSTALL MACOS

macOS Installation Guide

Complete installation guide for StreamTV on macOS.

Quick Start

Run the automated installation script:

./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 default channels
Create launch scripts
Optionally start the server

Manual Installation

If you prefer to install manually:

1. Install Python 3.8+

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

2. Install FFmpeg

Option A: Official Source (Recommended for Apple Silicon)

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/ffmpeg

Option B: Homebrew (Fallback)

brew install ffmpeg

3. Set Up Virtual Environment

python3 -m venv ~/.retro-tv-simulator/venv
source ~/.retro-tv-simulator/venv/bin/activate

4. Install Dependencies

pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

5. Configure

cp config.example.yaml config.yaml
# Edit config.yaml as needed

6. Initialize Database

python3 -c "from streamtv.database.session import init_db; init_db()"

7. Create Channels

python3 scripts/create_channel.py

8. Start Server

python3 -m streamtv.main

Installation Locations

Virtual Environment: ~/.streamtv/venv
Launch Script: ~/.streamtv/start_server.sh
Service Plist: ~/Library/LaunchAgents/com.streamtv.plist
Logs: ~/.streamtv/server.log

Running as a Service

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-simulator

Uninstallation

Run the uninstall script:

./uninstall_macos.sh

This will:

Stop the server
Remove the service
Remove installation files
Optionally remove the database

Troubleshooting

Python Not Found

If Python is not found after installation:

Restart your terminal
Check PATH: echo $PATH
Verify installation: /usr/local/bin/python3 --version

FFmpeg Not Found

If FFmpeg is not found:

Check if it's in PATH: which ffmpeg
For user installation: Add ~/.local/bin to PATH in ~/.zshrc:
```
export PATH="$HOME/.local/bin:$PATH"
```
Restart terminal or run: source ~/.zshrc

Port Already in Use

If port 8410 is already in use:

Change port in config.yaml:

QUICK START SWIFTUI

StreamTV SwiftUI Installer - Quick Start

🚀 Building the Native macOS Installer

Step 1: Build the Installer

Option A: Using Xcode (Recommended)

Open StreamTVInstaller/StreamTVInstaller.xcodeproj in Xcode
Select "My Mac" as destination
Press Cmd+B to build
The app will be in StreamTVInstaller/build/StreamTV Installer.app

Option B: Using Build Script

./build-installer.sh

Step 2: Run the Installer

Double-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

✨ Features

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

📋 What Gets Installed

Same as the Python installer:

✓ Python (opens installer if needed)
✓ FFmpeg (installs via Homebrew or direct download)
✓ Virtual environment
✓ Python dependencies
✓ Configuration
✓ Database
✓ Default channels
✓ Launch scripts

❓ Troubleshooting

"Xcode not found"

Install Xcode from the App Store, then:

xcode-select --install

"Build failed"

Make sure Xcode is up to date
Clean build: rm -rf build/
Rebuild in Xcode

"App won't open"

Right-click → Open (to bypass Gatekeeper)

🎯 Advantages

Better Performance: Native SwiftUI is faster
Modern UI: Follows macOS Human Interface Guidelines
Better Integration: Works seamlessly with macOS

SWIFTUI INSTALLER README

StreamTV SwiftUI Installer for macOS

Overview

The SwiftUI installer provides a native macOS experience with a beautiful, modern interface built using Apple's SwiftUI framework.

Features

Native macOS Experience

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

Visual Status Indicators

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

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

Building the Installer

Option 1: Using Xcode (Recommended)

Open StreamTVInstaller/StreamTVInstaller.xcodeproj in Xcode
Select "My Mac" as the destination
Press Cmd+B to build
Press Cmd+R to run
The app will be built in StreamTVInstaller/build/StreamTV Installer.app

Option 2: Using Build Script

./build-installer.sh

This will:

Build the SwiftUI app
Create a standalone .app bundle
Place it in the build/ directory

Option 3: Using Swift Package Manager

cd StreamTVInstaller
swift build -c release

Running the Installer

Double-Click Method

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)

Direct App Launch

Navigate to StreamTVInstaller/build/StreamTV Installer.app
Double-click the app
The installer will open

From Terminal

open "build/StreamTV Installer.app"

Requirements

macOS: 11.0 (Big Sur) or later
Xcode: 13.0 or later (for building)
Swift: 5.5 or later

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
✓ Creates default channels
✓ Creates launch scripts and launchd service

Advantages Over Tkinter

Native Experience

Better Performance: Native SwiftUI is faster than Tkinter
Modern UI: Follows macOS Human Interface Guidelines
Better Integration: Works seamlessly with macOS features

User Experience

Smooth Animations: Native macOS animations
Dark Mode: Automatic dark mode support
Accessibility: Full VoiceOver support
Native Dialogs: Uses macOS native alert dialogs

Development

Type Safety: Swift's type system prevents errors
Modern Language: Swift is Apple's modern language
Better Tooling: Xcode provides excellent debugging

Troubleshooting

"Xcode not found"

To build the SwiftUI installer, you need Xcode:

Install Xcode from the App Store
Open Xcode and accept the license
Install command line tools: xcode-select --install

"Build failed"

If the build fails:

Make sure Xcode is up to date
Check that all Swift files are in StreamTVInstaller/ directory
Try cleaning the build: rm -rf build/
Rebuild using Xcode

"App won't open"

If the app won't open:

Right-click the app → Open (to bypass Gatekeeper)
Check System Preferences → Security & Privacy
Make sure the app is notarized (for distribution)

YOUTUBE API SETUP

YouTube Data API v3 Integration Guide

Overview

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

Benefits

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

Setup Instructions

Step 1: Get a YouTube Data API v3 Key

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

Step 2: Configure StreamTV

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: null

Step 3: Restart StreamTV

Restart the StreamTV server for changes to take effect.

How It Works

With API Key (Recommended)

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

Without API Key (Fallback)

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

API Quota

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:

Go to Google Cloud Console
Navigate to "APIs & Services" > "Quotas"
Request a quota increase

Troubleshooting

API Key Invalid

Error: YouTube API quota exceeded or API key invalid

Solutions:

Verify your API key is correct in config.yaml
Ensure YouTube Data API v3 is enabled in Google Cloud Console
Check API key restrictions (if any) allow YouTube Data API v3

Quota Exceeded

Error: YouTube API quota exceeded

Solutions:

Wait for quota reset (daily at midnight Pacific Time)
Request quota increase in Google Cloud Console
StreamTV will fall back to yt-dlp-only mode

Video Not Found

Error: YouTube video not found via API

Possible Causes:

Video ID is invalid
Video has been deleted
Video is private/unlisted (if not authenticated)

Solutions:

Verify the YouTube URL is correct
Check if video is still available on YouTube
For private videos, use cookies authentication

Features

Video Validation

The API validates videos before attempting to stream:

# Example validation result
{
    'valid': True,
    'video_id': 'dQw4w9WgXcQ',
    'available': True,
    'info': {
        'title': 'Video Title',
        'duration': 212,
        'thumbnail': 'https://...',
        ...
    },
    'error': None
}

Enhanced Error Messages

With API integration, you get clearer error messages:

Before: "Error getting YouTube video info"
After: "YouTube video unavailable: Video is private"

Metadata Quality

API-provided metadata is more accurate: