{"id":34611551,"url":"https://github.com/anders94/tvhomerun-ios","last_synced_at":"2026-05-26T22:37:00.507Z","repository":{"id":325660282,"uuid":"1101951587","full_name":"anders94/tvhomerun-ios","owner":"anders94","description":"A SwiftUI-based streaming client for iOS that connects to a server running tvhomerun-web, enabling you to browse and watch video content on iPhone and iPad.","archived":false,"fork":false,"pushed_at":"2025-12-17T02:53:38.000Z","size":1158,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-20T16:55:57.582Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anders94.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-22T14:45:28.000Z","updated_at":"2025-12-17T02:53:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/anders94/tvhomerun-ios","commit_stats":null,"previous_names":["anders94/tvhomerun-ios"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/anders94/tvhomerun-ios","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Ftvhomerun-ios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Ftvhomerun-ios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Ftvhomerun-ios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Ftvhomerun-ios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anders94","download_url":"https://codeload.github.com/anders94/tvhomerun-ios/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Ftvhomerun-ios/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28003726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T14:16:04.836Z","updated_at":"2025-12-24T14:16:05.430Z","avatar_url":"https://github.com/anders94.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TV HomeRun for iOS\n\nA SwiftUI-based TV management and streaming client for iOS that connects to a server running [tvhomerun-backend](https://github.com/anders94/tvhomerun-backend). Watch live TV, manage your DVR schedule, and browse recorded content—all from your iPhone or iPad.\n\n## Features\n\n### Live TV\n- **Live Channel Streaming**: Watch live TV channels with HLS streaming and intelligent buffering\n- **Channel Guide**: Browse available channels with real-time program information\n- **Adaptive Playback**: Automatic buffer management to prevent stalls at the live edge\n\n### DVR Management\n- **Program Guide**: Comprehensive, searchable guide showing upcoming TV programs across all channels\n- **Recording Scheduling**: Create, modify, and delete series recording rules\n- **Visual Indicators**: Clear display of scheduled and active recordings in the guide\n- **Series Management**: One-tap recording toggle for entire series\n\n### Recorded Content\n- **Content Library**: Grid-based browsing of recorded shows with thumbnails and metadata\n- **Episode Management**: Detailed episode lists with progress tracking and swipe-to-delete\n- **Advanced Playback**: Resume functionality, seek controls, and auto-play for subsequent episodes\n- **Progress Tracking**: Automatic bookmark saving with visual watch indicators\n\n### System Features\n- **Server Configuration**: Persistent URL storage with automatic connectivity validation\n- **Error Resilience**: Exponential backoff retry logic (1s, 2s, 4s intervals) with user notifications after 5 seconds\n- **Touch-Optimized UI**: iOS-specific interface design optimized for both iPhone and iPad\n\n## Requirements\n\n- iOS 15.0+\n- Xcode 14.0+\n- Swift 5.7+\n- A server running [tvhomerun-backend](https://github.com/anders94/tvhomerun-backend)\n\n## Installation\n\n1. Clone the repository: `git clone https://github.com/anders94/tvhomerun-ios.git\n2. Double-click the `.xcodeproj` file to open in Xcode\n3. Select your target device or simulator\n4. Press ⌘+R to build and run\n\n## Project Structure\n\n```\nTVHomeRun/\n├── TVHomeRun/\n│   ├── TVHomeRunApp.swift          # App entry point\n│   ├── ContentView.swift           # Root view with connectivity check\n│   ├── Info.plist                  # App configuration\n│   ├── Models/\n│   │   ├── Health.swift            # Health check data model\n│   │   ├── Episode.swift           # Episode data model\n│   │   ├── Show.swift              # Show data model\n│   │   ├── Guide.swift             # Program guide data models\n│   │   ├── RecordingRule.swift     # Recording rule data models\n│   │   └── Channel.swift           # Live channel data models\n│   ├── Services/\n│   │   └── APIClient.swift         # API client with error handling\n│   ├── Utilities/\n│   │   └── UserSettings.swift      # UserDefaults wrapper\n│   └── Views/\n│       ├── ServerSetupView.swift         # Server URL configuration\n│       ├── ShowsListView.swift           # Recorded shows grid view\n│       ├── EpisodesListView.swift        # Episodes list view\n│       ├── GuideView.swift               # Program guide view\n│       ├── GuideDetailView.swift         # Program guide detail view\n│       ├── LiveChannelsView.swift        # Live channel browser\n│       ├── LiveVideoPlayerView.swift     # Live TV player view\n│       ├── LiveVideoPlayerViewModel.swift # Live player state management\n│       ├── VideoPlayerView.swift         # Recorded video player view\n│       └── VideoPlayerViewModel.swift    # Recorded player state management\n├── CHANGELOG.md                     # Development history\n└── README.md                        # This file\n```\n\n## Architecture\n\nThe app follows the MVVM (Model-View-ViewModel) architecture pattern:\n\n### Models Layer\n- **Channel**: Represents live TV channels with guide numbers and metadata\n- **Show**: Represents recorded TV shows with metadata\n- **Episode**: Represents recorded episodes with playback tracking\n- **Health**: Server health status and connectivity validation\n- **Guide**: Program guide data (GuideResponse, GuideChannel, GuideProgram, GuideSeries)\n- **RecordingRule**: Recording rules for series with configuration options\n\n### Services Layer\n- **APIClient**: Handles all network requests with exponential backoff retry logic\n  - Automatically retries failed requests up to 3 times\n  - Uses 1s, 2s, 4s backoff intervals\n  - Shows error alerts after 5 seconds of failures\n  - Manages live streaming sessions with heartbeat mechanism\n\n### Views Layer\n\n**Live TV**\n- **LiveChannelsView**: Channel browser with current program information\n- **LiveVideoPlayerView**: Full-screen live TV player with AVPlayer\n- **LiveVideoPlayerViewModel**: Manages live stream buffering, heartbeat, and playback state\n\n**DVR Management**\n- **GuideView**: Searchable program guide with recording indicators across all channels\n- **GuideDetailView**: Detailed program view with series recording toggle\n\n**Recorded Content**\n- **ShowsListView**: Grid display of recorded shows with thumbnails\n- **EpisodesListView**: Episode list with progress tracking and swipe-to-delete\n- **VideoPlayerView**: Full-screen player for recorded content with native iOS controls\n- **VideoPlayerViewModel**: Manages playback state, progress tracking, and episode navigation\n\n**Configuration**\n- **ServerSetupView**: Server URL configuration with validation\n\n### Utilities\n- **UserSettings**: Persistent storage for server URL and setup state\n\n## API Integration\n\nThe app communicates with the following endpoints:\n\n**System**\n- `GET /health` - Server connectivity verification\n\n**Live TV**\n- `GET /api/channels` - Retrieve available live TV channels\n- `POST /api/start-watching` - Start live TV stream and obtain playlist URL\n- `POST /api/heartbeat` - Maintain live streaming session\n- `POST /api/stop-watching` - End live TV stream and cleanup session\n\n**DVR Management**\n- `GET /api/guide` - Retrieve program guide (optional forceRefresh parameter)\n- `GET /api/recording-rules` - Retrieve all recording rules\n- `POST /api/recording-rules` - Create new series recording rule\n- `DELETE /api/recording-rules/:id` - Delete recording rule\n\n**Recorded Content**\n- `GET /api/shows` - Retrieve recorded shows\n- `GET /api/shows/:id/episodes` - Retrieve episodes for a show\n- `PUT /api/episodes/:id/progress` - Update playback progress\n- `DELETE /api/episodes/:id` - Delete episode (optional rerecord parameter)\n\n## Configuration\n\n### HTTP Support\n\nThe app requires HTTP support for local network servers. This is configured in `Info.plist`:\n\n```xml\n\u003ckey\u003eNSAppTransportSecurity\u003c/key\u003e\n\u003cdict\u003e\n    \u003ckey\u003eNSAllowsArbitraryLoads\u003c/key\u003e\n    \u003ctrue/\u003e\n\u003c/dict\u003e\n```\n\n**Note**: This setting allows unencrypted HTTP connections. This is appropriate for local network servers but should not be used for production apps communicating over the internet.\n\n## Key Differences from Apple TV Version\n\nThis iOS version shares the core functionality with the tvOS version while being optimized for mobile:\n\n**Shared Capabilities**\n- Live TV streaming with HLS support\n- Complete DVR schedule management\n- Recorded content library and playback\n- Program guide with search and filtering\n- Series recording rules\n\n**iOS-Specific Adaptations**\n- **UI Scaling**: Adjusted font sizes, spacing, and component sizes for smaller screens\n- **Grid Layout**: 2-column grid instead of 4-column for mobile devices\n- **Touch Navigation**: Standard iOS touch navigation instead of tvOS focus engine\n- **Button Styles**: iOS-native button styles instead of tvOS card styles\n- **Responsive Design**: Adaptive layouts optimized for both iPhone and iPad\n- **Portability**: Watch live TV or manage recordings from anywhere on your network\n\n## Usage\n\n### Initial Setup\n1. **First Launch**: Enter your server URL (e.g., `http://192.168.1.100:3000`)\n2. **Connectivity Check**: The app validates the connection before proceeding\n\n### Live TV\n1. **Access Live TV**: Tap the \"Live TV\" icon in the navigation bar\n2. **Browse Channels**: Scroll through available channels with current program information\n3. **Watch Live**: Tap a channel to start live streaming\n4. **Buffer Management**: The app maintains a 10-second buffer to prevent stalls\n5. **Exit Stream**: Tap back to return to the channel list\n\n### Managing Recordings\n1. **Open Program Guide**: Tap the magnifying glass icon in the navigation bar\n2. **Browse Programs**: View upcoming programs across all channels\n3. **Search**: Use the search bar to find specific shows\n4. **Schedule Recording**: Tap a program, then toggle \"Record This Series\"\n5. **Visual Indicators**: Recording status is displayed with icons in the guide\n6. **Modify Schedule**: Toggle off \"Record This Series\" to cancel future recordings\n7. **Force Refresh**: Pull down on the guide to force a refresh of program data\n\n### Watching Recorded Content\n1. **Browse Library**: View recorded shows in the main grid view\n2. **Select Show**: Tap a show to view its episodes\n3. **Watch Episode**: Tap an episode to start playback\n4. **Resume**: Episodes automatically resume from where you left off\n5. **Auto-Play**: Next episode plays automatically when the current episode ends\n6. **Progress Tracking**: Watch progress is automatically saved as you view\n\n### Managing Episodes\n1. **Delete Episode**: Swipe left on an episode and tap Delete\n2. **Re-record Option**: When deleting, choose whether to allow re-recording\n3. **Long-Press Menu**: Long-press an episode for additional options\n\n## Development\n\n### Building for Simulator\n\n```bash\n# List available simulators\nxcrun simctl list devices\n\n# Build and run\nxcodebuild -scheme TVHomeRun -destination 'platform=iOS Simulator,name=iPhone 15' build\n```\n\n### Building for Device\n\n1. Connect your iOS device\n2. Select your device in Xcode\n3. Ensure your development team is selected in Signing \u0026 Capabilities\n4. Press ⌘+R to build and run\n\n## Testing\n\nFor testing, you'll need a server running locally at a specified port (default: 3000) that implements the API endpoints. See [tvhomerun-backend](https://github.com/anders94/tvhomerun-backend) for the server implementation.\n\n## Troubleshooting\n\n### Cannot Connect to Server\n\n- Ensure your iOS device and server are on the same network\n- Verify the server URL is correct (include `http://` and port number)\n- Check that your server is running and accessible\n- Try accessing the server URL in Safari on your device\n\n### Live TV Issues\n\n**Stream Won't Start**\n- Verify the backend has access to your HDHomeRun device\n- Check that the channel is available and has a signal\n- Ensure no other client is already watching (check backend logs)\n\n**Playback Stalls or Buffers**\n- The app uses a 10-second forward buffer by default\n- If stalling persists, check your network connection quality\n- Verify the backend transcoding process is running smoothly\n- Monitor backend logs for encoding issues\n\n**Stream Stops After Some Time**\n- Check backend logs for heartbeat timeout messages\n- Ensure the app remains in the foreground during playback\n- Verify network stability between device and server\n\n### Recorded Video Issues\n\n**Video Won't Play**\n- Verify the video URL is accessible from your device\n- Check that the video format is supported by iOS (H.264, HEVC)\n- Ensure your server is properly serving the video files\n\n**Progress Not Saving**\n- Check network connectivity during playback\n- Verify the backend API is responding to progress updates\n- Check for errors in the Xcode console\n\n### Recording Schedule Issues\n\n**Cannot Create Recording Rule**\n- Ensure the program guide data is loaded\n- Check that the series information is available\n- Verify backend recording rule creation endpoint is working\n\n**Recording Indicator Not Showing**\n- Force refresh the guide by pulling down\n- Check that recording rules are properly synced with backend\n\n### General Issues\n\n**App Crashes on Launch**\n- Clean build folder (⌘+Shift+K)\n- Delete derived data\n- Rebuild the project\n\n**UI Not Updating**\n- Check console for API errors\n- Verify server connectivity\n- Try force-quitting and restarting the app\n\n## Related Projects\n\n- [tvhomerun-backend](https://github.com/anders94/tvhomerun-backend) - Server implementation\n- [tvhomerun-tvos](https://github.com/anders94/tvhomerun-tvos) - Apple TV version\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanders94%2Ftvhomerun-ios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanders94%2Ftvhomerun-ios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanders94%2Ftvhomerun-ios/lists"}