simvision/README.md

SimVision - tvOS VOD Streaming Application

A SwiftUI-based tvOS application for streaming Video On Demand content from XStream-compatible m3u playlists.

Overview

SimVision is a tvOS app that:

• Authenticates via a custom web service
• Retrieves XStream server credentials
• Fetches and parses m3u playlists
• Displays VOD content in a tvOS-optimized interface
• Plays video streams using AVPlayer

Project Status

All source files have been created (24 Swift files). The Xcode project needs to be created and configured.

Setup Instructions

1. Create Xcode Project

1. Open Xcode
2. Select File > New > Project
3. Choose tvOS > App
4. Configure the project:
   • Product Name: simvision
   • Organization Identifier: com.yourdomain (replace with your identifier)
   • Interface: SwiftUI
   • Language: Swift
   • Minimum Deployment: tvOS 17.0 or later
5. Save the project in /Users/michaelsimard/dev/tvos/simvision

2. Add Source Files to Xcode

1. In Xcode, select the simvision folder in the Project Navigator
2. Right-click and select Add Files to "simvision"...
3. Navigate to the simvision directory containing the Swift files
4. Select all folders (App, Models, Views, Services, etc.)
5. Ensure "Create groups" is selected
6. Ensure "Add to targets: simvision" is checked
7. Click Add

3. Configure Project Settings

Required Capabilities

1. Select the project in the Project Navigator
2. Select the simvision target
3. Go to Signing & Capabilities
4. Click + Capability
5. Add Outgoing Connections (Client) - required for network requests

Update Constants

Edit simvision/Utilities/Constants.swift:

enum API {
    static let authenticationBaseURL = "https://your-actual-web-service.com"
    static let authenticationEndpoint = "/api/auth"
    // ... rest of configuration
}

Replace "https://your-actual-web-service.com" with your actual web service URL.

4. Build and Run

1. Select Product > Build (⌘B) to compile
2. Select a tvOS Simulator from the scheme selector
3. Select Product > Run (⌘R) to launch the app

Project Structure

simvision/
├── App/
│   ├── simvisionApp.swift           # App entry point
│   └── AppState.swift                # Global state coordinator
├── Models/
│   ├── Credentials.swift             # Authentication models
│   ├── VODItem.swift                 # VOD item model
│   ├── Playlist.swift                # Playlist container
│   └── APIResponse.swift             # API response models
├── Views/
│   ├── Authentication/
│   │   └── PasswordEntryView.swift   # Login screen
│   ├── Main/
│   │   ├── MainTabView.swift         # Root navigation
│   │   └── VODLibraryView.swift      # VOD grid
│   ├── Detail/
│   │   └── VODDetailView.swift       # Video details
│   ├── Player/
│   │   └── VideoPlayerView.swift     # Video player
│   └── Components/
│       ├── VODCardView.swift         # Thumbnail card
│       ├── LoadingView.swift         # Loading indicator
│       └── ErrorView.swift           # Error display
├── Services/
│   ├── NetworkService.swift          # HTTP client
│   ├── AuthenticationService.swift   # Authentication logic
│   ├── PlaylistService.swift         # Playlist fetching
│   └── StorageService.swift          # Secure storage
├── Parsers/
│   └── M3UParser.swift               # M3U playlist parser
├── ViewModels/
│   ├── AuthenticationViewModel.swift
│   ├── VODLibraryViewModel.swift
│   └── VideoPlayerViewModel.swift
└── Utilities/
    ├── Constants.swift                # App constants
    ├── Extensions.swift               # Swift extensions
    └── NetworkError.swift             # Error types

Architecture

Authentication Flow

1. User enters password in PasswordEntryView
2. AuthenticationService sends password to web service via header
3. Web service returns XStream credentials (server, port, username, password)
4. Credentials are stored securely in Keychain via StorageService
5. App navigates to MainTabView

Playlist Flow

1. PlaylistService constructs XStream URL with credentials
2. Downloads m3u playlist from XStream server
3. M3UParser parses m3u format and extracts VOD items
4. VODLibraryView displays items in a grid
5. User selects item → VODDetailView → VideoPlayerView

State Management

• AppState: Central ObservableObject managing authentication, credentials, and playlist
• Environment Object pattern distributes state to all views
• ViewModels handle view-specific logic

Web Service API Requirements

Your authentication web service should implement:

Endpoint: POST /api/auth

Request Headers:

X-Password: user_entered_password

Response (200 OK):

{
  "serverUrl": "example.com",
  "port": "8080",
  "username": "user123",
  "password": "pass456"
}

Error Response (401/403):

{
  "error": "Authentication failed"
}

XStream Integration

The app fetches playlists using the XStream API format:

http://server:port/get.php?username=X&password=Y&type=m3u_plus&output=ts

Expected m3u format:

#EXTM3U
#EXTINF:-1 tvg-id="123" tvg-name="Movie Name" tvg-logo="http://..." group-title="Movies",Movie Name
http://server:port/movie/username/password/12345.mp4

Features

Implemented

• ✅ Password-based authentication
• ✅ XStream credentials retrieval
• ✅ M3U playlist parsing (VOD)
• ✅ VOD library grid view
• ✅ Category filtering
• ✅ Video playback with AVPlayer
• ✅ Secure credential storage (Keychain)
• ✅ Error handling and display
• ✅ Loading states
• ✅ tvOS focus engine support

Future Enhancements

• Live TV streams
• Electronic Program Guide (EPG)
• Favorites/watchlist
• Search functionality
• Continue watching
• Multiple profiles

Troubleshooting

Build Errors

1. Missing imports: Ensure all files are added to the target
2. Deployment target: Verify tvOS 17.0+ is selected
3. Code signing: Configure signing in project settings

Runtime Issues

1. Authentication fails: Check web service URL in Constants.swift
2. Playlist not loading: Verify XStream server credentials
3. Videos not playing: Ensure URLs are valid and accessible

Network Debugging

The app includes comprehensive error messages with recovery suggestions. Check:

• NetworkError enum for error types
• Console logs for detailed error information
• Network connectivity

Testing

Simulator Testing

1. Use the tvOS Simulator in Xcode
2. Navigate with mouse clicks or keyboard (arrow keys = D-pad)
3. Test focus states and navigation flow

Device Testing

1. Connect Apple TV via Xcode
2. Select device as run destination
3. Test with Siri Remote for actual user experience

Requirements

• Xcode: 15.0 or later
• tvOS: 17.0 or later
• Swift: 5.9 or later
• Frameworks: SwiftUI, AVKit, Combine, Foundation

Security Notes

• User passwords are never stored, only transmitted once
• XStream credentials are stored in Keychain (encrypted)
• No logging of sensitive information
• HTTPS recommended for web service (update Constants.swift)

License

Copyright © 2026. All rights reserved.