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

```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):
```json
{
  "serverUrl": "example.com",
  "port": "8080",
  "username": "user123",
  "password": "pass456"
}
```

**Error Response** (401/403):
```json
{
  "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.