Initial commit: SimVision tvOS streaming app
Features: - VOD library with movie grouping and version detection - TV show library with season/episode organization - TMDB integration for trending shows and recently aired episodes - Recent releases section with TMDB release date sorting - Watch history tracking with continue watching - Playlist caching (12-hour TTL) for offline support - M3U playlist parsing with XStream API support - Authentication with credential storage Technical: - SwiftUI for tvOS - Actor-based services for thread safety - Persistent caching for playlists, TMDB data, and watch history - KSPlayer integration for video playback Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
258
README.md
Normal file
258
README.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user