{"id":34611547,"url":"https://github.com/anders94/tvhomerun-tvos","last_synced_at":"2026-05-28T19:31:34.723Z","repository":{"id":325660515,"uuid":"1099287000","full_name":"anders94/tvhomerun-tvos","owner":"anders94","description":"A SwiftUI-based AppleTV application for streaming video content from a local network server running tvhomerun-web.","archived":false,"fork":false,"pushed_at":"2025-12-17T04:48:34.000Z","size":1820,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-20T18:26:06.616Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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-18T20:09:33.000Z","updated_at":"2025-12-17T04:48:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/anders94/tvhomerun-tvos","commit_stats":null,"previous_names":["anders94/tvhomerun-appletv","anders94/tvhomerun-tvos"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/anders94/tvhomerun-tvos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Ftvhomerun-tvos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Ftvhomerun-tvos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Ftvhomerun-tvos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Ftvhomerun-tvos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anders94","download_url":"https://codeload.github.com/anders94/tvhomerun-tvos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anders94%2Ftvhomerun-tvos/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.292Z","updated_at":"2025-12-24T14:16:04.897Z","avatar_url":"https://github.com/anders94.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TV HomeRun - tvOS\n\nA SwiftUI-based TV management and streaming client for AppleTV 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 AppleTV.\n\n## Features\n\n### Live TV \u0026 Recording Management\n- **Watch Live TV** with seamless channel switching and program information\n- **Browse and search the program guide** to discover what's on now and coming up\n- **Schedule recordings** directly from the guide or show pages\n- **Manage your recording schedule** - add, modify, or cancel recordings on the fly\n- **Quick recording controls** from episode views for immediate scheduling\n\n### Content Library \u0026 Playback\n- **Browse your recorded shows** with rich thumbnails and metadata\n- **Episode library** with progress indicators and watch status tracking\n- **Advanced video player** featuring:\n  - Resume playback from last position\n  - Skip forward 30 seconds / Skip backward 15 seconds\n  - Precise scrubbing controls\n  - Automatic episode navigation (next/previous)\n  - Auto-play next episode when current episode ends\n\n### Technical Excellence\n- **Server URL configuration** with automatic persistence\n- **Intelligent error handling** with exponential backoff for network resilience\n- **Beautiful tvOS-optimized UI** following Apple's design guidelines\n- **Reliable performance** with efficient API communication\n\n## Project Setup\n\n### Option 1: Create Project in Xcode (Recommended)\n\n1. **Open Xcode** and select \"Create a new Xcode project\"\n2. Choose **tvOS** → **App** template\n3. Configure the project:\n   - Product Name: `TVHomeRun`\n   - Interface: `SwiftUI`\n   - Language: `Swift`\n   - Save location: Choose the parent directory of this folder\n4. **Delete** the default files Xcode creates:\n   - `ContentView.swift` (if different from ours)\n   - Any other default files\n5. **Add all source files** from the `TVHomeRun` folder to your project:\n   - Right-click on the project in the navigator\n   - Select \"Add Files to TVHomeRun...\"\n   - Select the entire `TVHomeRun` folder\n   - Check \"Copy items if needed\"\n   - Click \"Add\"\n6. **Replace Info.plist** with the provided one (or merge the `NSAppTransportSecurity` settings)\n7. **Build and Run** on AppleTV Simulator or device\n\n### Option 2: Manual Project File Creation\n\nIf you prefer, I can generate a complete `.xcodeproj` file structure for you.\n\n## Project Structure\n\n```\nTVHomeRun/\n├── TVHomeRun/\n│   ├── Models/\n│   │   ├── Show.swift          # Show data model\n│   │   ├── Episode.swift       # Episode data model\n│   │   └── Health.swift        # Health check model\n│   ├── Services/\n│   │   └── APIClient.swift     # Network client with error handling\n│   ├── Utilities/\n│   │   └── UserSettings.swift  # UserDefaults wrapper\n│   ├── Views/\n│   │   ├── ServerSetupView.swift       # URL configuration\n│   │   ├── ShowsListView.swift         # Shows grid\n│   │   ├── EpisodesListView.swift      # Episodes list\n│   │   ├── VideoPlayerView.swift       # Custom player UI\n│   │   └── VideoPlayerViewModel.swift  # Player logic\n│   ├── TVHomeRunApp.swift    # App entry point\n│   └── ContentView.swift       # Root navigation\n├── Info.plist\n└── README.md\n```\n\n## API Endpoints\n\nThe application integrates with the following backend endpoints:\n\n### System\n- `GET /health` - Health check\n  - Returns: `{\"status\":\"ok\",\"timestamp\":\"...\",\"uptime\":123,...}`\n\n### Content Library\n- `GET /api/shows` - List all recorded shows\n  - Returns: `{\"shows\":[...],\"count\":19}`\n\n- `GET /api/shows/:id/episodes` - List episodes for a show\n  - Returns: `{\"episodes\":[...],\"count\":23,\"show\":{...}}`\n\n### Live TV \u0026 Guide\n- `GET /api/channels` - List available channels\n- `GET /api/guide` - Retrieve program guide data\n- `GET /api/guide/search` - Search the program guide\n- `GET /api/live/:channelId` - Stream live TV from a channel\n\n### Recording Management\n- `GET /api/recordings` - List scheduled recordings\n- `POST /api/recordings` - Schedule a new recording\n- `PUT /api/recordings/:id` - Modify an existing recording\n- `DELETE /api/recordings/:id` - Cancel a scheduled recording\n\n## Configuration\n\n### Server URL\n\nOn first launch, the app will prompt for the server URL. The default action is \"Accept\" which validates the URL and connects to the server.\n\nExample URLs:\n- `http://192.168.1.100:3000`\n- `http://localhost:3000`\n- `http://homerun.local:3000`\n\n### Network Security\n\nThe app includes `NSAppTransportSecurity` settings to allow HTTP connections to local servers. For production use, consider using HTTPS.\n\n## Remote Control Mapping\n\n### During Playback\n- **Select/Touch Surface**: Show/hide player controls\n- **Play/Pause**: Toggle playback\n- **Menu**: Exit player and return to previous screen\n- **Swipe Left/Right**: Navigate through episodes (recorded content) or channels (live TV)\n- **Skip Forward**: Jump ahead 30 seconds\n- **Skip Backward**: Jump back 15 seconds\n\n### Navigation\n- **Select/Touch Surface**: Select items, activate buttons\n- **Swipe**: Navigate through content grids and lists\n- **Menu**: Navigate back to previous screen\n\n## Technical Details\n\n### Error Handling\n\n- Exponential backoff with 1s, 2s, 4s intervals (max 5s)\n- User notification after 5 seconds of retry attempts\n- Graceful degradation on network errors\n\n### Video Playback\n\n- Uses AVPlayer for video streaming\n- Supports HTTP streaming protocols\n- Auto-resume from last playback position\n- Auto-play next episode when current episode ends\n\n### Data Persistence\n\n- Server URL saved to UserDefaults\n- Persists between app launches\n- Editable from the shows list via settings gear icon\n\n## Development\n\nBuilt with:\n- SwiftUI\n- AVKit/AVFoundation\n- Combine\n- URLSession\n\nTarget:\n- tvOS 15.0+\n- Xcode 14.0+\n- Swift 5.7+\n\n## Testing\n\nA test server is expected to be running at `http://localhost:3000` during development. The server should implement the API endpoints listed above.\n\n## Future Enhancements\n\n- Resume position sync with server\n- Mark episodes as watched\n- Content filtering by category and genre\n- Series recording management (season passes)\n- Picture-in-picture support for tvOS\n- Parental controls\n- Multi-user profiles with personalized recommendations\n- Cloud DVR integration\n- Conflict detection and resolution for overlapping recordings\n\n## License\n\nCreated for TV HomeRun project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanders94%2Ftvhomerun-tvos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanders94%2Ftvhomerun-tvos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanders94%2Ftvhomerun-tvos/lists"}