{"id":47734226,"url":"https://github.com/edvin/cast","last_synced_at":"2026-04-24T22:01:09.800Z","repository":{"id":348598753,"uuid":"1198636554","full_name":"edvin/cast","owner":"edvin","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-18T20:46:09.000Z","size":19945,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T21:31:16.772Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edvin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2026-04-01T15:58:54.000Z","updated_at":"2026-04-18T20:33:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/edvin/cast","commit_stats":null,"previous_names":["edvin/cast"],"tags_count":43,"template":false,"template_full_name":null,"purl":"pkg:github/edvin/cast","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edvin%2Fcast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edvin%2Fcast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edvin%2Fcast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edvin%2Fcast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edvin","download_url":"https://codeload.github.com/edvin/cast/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edvin%2Fcast/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32242315,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2026-04-02T22:14:54.455Z","updated_at":"2026-04-24T22:01:09.781Z","avatar_url":"https://github.com/edvin.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cast\n\nA local network media server, Apple TV client, and desktop management app for streaming your video library. A Rust server indexes your media folders, fetches metadata and artwork from TMDB, and streams video with automatic MKV→MP4 remuxing. A tvOS app discovers the server via Bonjour and provides a cinematic browsing and playback experience. A Tauri desktop app provides a system tray server with library management, drag-and-drop import, and real-time monitoring.\n\n## Architecture\n\n```\n┌─────────────┐        HTTP (LAN)        ┌──────────────┐\n│  Apple TV   │ ◄──────────────────────► │  Cast Server  │\n│  tvOS App   │   Browse, stream, track  │  (Rust/axum)  │\n│  (SwiftUI)  │   Bonjour discovery      │  Your PC/Mac  │\n└─────────────┘                          └──────────────┘\n```\n\n## Media Library Setup\n\nOrganize your media directory with one subfolder per show:\n\n```\nmedia/\n├── Planet Earth/\n│   ├── S01E01 From Pole to Pole.mp4\n│   ├── S01E02 Mountains.mkv\n│   └── ...\n├── Cosmos/\n│   ├── 01x01 - Standing Up in the Milky Way.mp4\n│   └── ...\n└── The Joy of Painting/\n    ├── Episode 01 - A Walk in the Woods.mp4\n    └── ...\n```\n\n**Episode naming** — these patterns are auto-parsed for season/episode numbers:\n- `S01E03 - Episode Title.mp4` (also works with scene-release names like `show.name.s01e03.720p.web.mkv`)\n- `01x03 - Title.mp4`\n- `Episode 03 - Title.mp4`\n- `03 - Title.mp4`\n- `03.mp4`\n\n**Video formats** — MP4/MOV files play natively. MKV, AVI, and WebM files are automatically remuxed to MP4 in the background when detected (requires ffmpeg). The original file is deleted once remuxing completes. HEVC 10-bit video is transcoded to H.264 for Apple TV compatibility. If a file hasn't been remuxed yet when you hit play, it streams on-the-fly.\n\n**Subtitles** — external `.srt` files are detected alongside video files:\n- `S01E01.srt` — matches `S01E01.mp4`, defaults to English\n- `S01E01.en.srt` — English subtitles\n- `S01E01.sv.srt` — Swedish subtitles\n- Multiple languages supported per episode\n\nEmbedded subtitles in the video container (MKV/MP4) are preserved during remux and appear in the tvOS player's subtitle picker.\n\n**Artwork** — place any of these in a show folder and they'll be detected automatically:\n- Poster: `.poster.jpg`, `.poster.png` (also accepts legacy: `poster.jpg`, `folder.jpg`, `cover.jpg`)\n- Backdrop: `.backdrop.jpg`, `.backdrop.png` (also accepts: `backdrop.jpg`, `fanart.jpg`)\n\nOr let TMDB fetch artwork automatically (see below).\n\n## Quick Start\n\n### 1. Build the server\n\n```bash\ncd server\ncargo build --release\n```\n\nRequires [Rust](https://rustup.rs/). The binary is at `server/target/release/cast-server`.\n\n### 2. Configure\n\nCreate `server/.env`:\n\n```env\nCAST_MEDIA_PATH=/path/to/your/media\nTMDB_API_KEY=your-tmdb-api-key\nCAST_SERVER_NAME=Living Room\n```\n\nGet a free TMDB API key at [themoviedb.org/settings/api](https://www.themoviedb.org/settings/api) (optional but recommended — provides descriptions, episode info, cast, and artwork).\n\n### 3. Run\n\n```bash\ncd server\ncargo run --release\n```\n\nThe server starts on port 3456 and advertises itself via Bonjour.\n\n### 4. Desktop app (recommended for Windows/macOS)\n\nDownload the installer from [Releases](../../releases):\n- **Windows**: `Cast Server Setup.exe`\n- **macOS**: `Cast Server.dmg`\n\nThe desktop app includes:\n- System tray icon — server runs in the background\n- Library browser with artwork, episode details, and file status\n- Drag-and-drop import — drop video files to auto-organize into series folders\n- Remux management — convert MKV files to MP4 with one click\n- Delete watched episodes — bulk cleanup with file size info\n- Settings UI — configure media path, TMDB key, server name\n- Real-time log viewer\n\n### 5. Install the tvOS app\n\nOpen `Cast/Cast.xcodeproj` in Xcode, select your Apple TV as the run destination, and deploy. The app auto-discovers the server on the local network.\n\n## Server Configuration\n\nAll options can be set via CLI flags, environment variables, or `.env` file:\n\n| Flag | Env Var | Default | Description |\n|------|---------|---------|-------------|\n| `--media` | `CAST_MEDIA_PATH` | *(required)* | Path to media directory |\n| `--port` | — | `3456` | HTTP port |\n| `--name` | `CAST_SERVER_NAME` | `Cast Server` | Bonjour display name |\n| `--tmdb-key` | `TMDB_API_KEY` | *(none)* | TMDB API key for metadata |\n| `--log-file` | — | `false` | Log to files instead of stdout |\n\n## TMDB Metadata\n\nWhen a TMDB API key is configured, the server automatically:\n\n- Searches TMDB by folder name (cleans common tags like year, resolution, encoding)\n- Downloads poster and backdrop artwork\n- Fetches show info: title, overview, genres, rating, year\n- Fetches episode info: title, overview, air date, runtime, cast \u0026 guest stars\n\n**If auto-matching fails**, create a `tmdb.txt` file in the show's folder containing just the TMDB ID:\n\n```\n# Find the ID at https://www.themoviedb.org/tv/\necho 12345 \u003e \"/path/to/media/My Show/tmdb.txt\"\n```\n\nYou can also trigger a metadata refresh from the app (Refresh button) or via the API:\n\n```bash\ncurl -X POST http://localhost:3456/api/metadata/fetch\n```\n\n## Dependencies\n\n- **ffmpeg** (recommended) — **required** for MKV/AVI/WebM files. The server automatically converts these to MP4 in the background and deletes the originals. Without ffmpeg, only native MP4/MOV files will play.\n- **ffprobe** — enables video duration detection (bundled with ffmpeg)\n\nInstall via your package manager:\n\n| Platform | Command |\n|----------|---------|\n| macOS | `brew install ffmpeg` |\n| Windows | `winget install ffmpeg` or download from [gyan.dev/ffmpeg/builds](https://www.gyan.dev/ffmpeg/builds/) and add to PATH |\n| Linux | `apt install ffmpeg` / `dnf install ffmpeg` |\n\n## Windows Deployment\n\n1. Download `cast-server-windows-amd64.exe` from [Releases](../../releases)\n2. Place it in a folder (e.g. `C:\\Cast\\`)\n3. Copy `scripts\\install-windows.ps1` and `scripts\\uninstall-windows.ps1` into the same folder\n4. Create a `.env` file next to the binary:\n```\nCAST_MEDIA_PATH=D:\\Media\nTMDB_API_KEY=your-key\nCAST_SERVER_NAME=Living Room\n```\n5. Run from PowerShell:\n```powershell\n.\\install-windows.ps1\n```\n\nThis creates a Task Scheduler entry that auto-starts at login with file logging. Logs go to `\u003cmedia-dir\u003e\\logs\\`.\n\n```powershell\n# Management\nStop-ScheduledTask -TaskName CastServer\nStart-ScheduledTask -TaskName CastServer\n.\\uninstall-windows.ps1\n```\n\n### Wake-on-LAN\n\nThe tvOS app stores the server's MAC address after a successful connect and\nshows a **Wake Server** button on the \"Server Unreachable\" screen. Tap it to\nbroadcast a magic packet on the local subnet. For this to actually wake a\nsleeping Windows machine you need:\n\n1. **BIOS / UEFI** — enable \"Wake on LAN\" / \"Power on by PCI-E\" / \"Resume by PME\"\n   (wording varies by vendor).\n2. **Network adapter** in Windows Device Manager → *Properties* → *Power\n   Management*: enable **Allow this device to wake the computer** and\n   **Only allow a magic packet to wake the computer**. On the *Advanced* tab,\n   set **Wake on Magic Packet** = Enabled. If present, also enable\n   **Wake on pattern match**.\n3. **Windows power plan** — disable Fast Startup\n   (Control Panel → Power Options → *Choose what the power button does* →\n   uncheck *Turn on fast startup*). Fast Startup leaves the NIC in an\n   unpowered state where WoL doesn't work on most adapters.\n4. **Router/switch** — WoL is a local-network feature. The magic packet has\n   to reach the server's subnet; cross-subnet WoL is out of scope here.\n\nYou can verify WoL works from another machine on the LAN with `wakeonlan`\n(macOS: `brew install wakeonlan`) or any Windows WoL utility, independent of\nthe Cast app.\n\n## API\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/continue-watching` | In-progress shows, sorted by recency |\n| GET | `/api/series` | All shows with metadata and watch summary |\n| GET | `/api/series/{id}` | Show detail with episodes |\n| GET | `/api/series/{id}/next` | Smart next episode recommendation |\n| GET | `/api/series/{id}/art` | Poster image |\n| GET | `/api/series/{id}/backdrop` | Backdrop image |\n| DELETE | `/api/series/{id}` | Delete series and all files |\n| DELETE | `/api/series/{id}/progress` | Reset all watch progress for a show |\n| POST | `/api/series/{id}/remux` | Trigger MKV→MP4 remux for all episodes |\n| GET | `/api/episodes/{id}/stream` | Video stream (byte-range, auto-remux) |\n| GET | `/api/episodes/{id}/thumbnail` | Episode thumbnail |\n| GET | `/api/episodes/{id}/progress` | Watch progress |\n| POST | `/api/episodes/{id}/progress` | Update watch progress |\n| DELETE | `/api/episodes/{id}/progress` | Mark episode as unwatched |\n| GET | `/api/episodes/{id}/credits` | Cast \u0026 guest stars (from TMDB, cached) |\n| GET | `/api/episodes/{id}/subtitles` | List available subtitle languages |\n| GET | `/api/episodes/{id}/subtitles/{lang}` | Subtitle file (SRT converted to WebVTT) |\n| DELETE | `/api/episodes/{id}` | Delete episode and related files |\n| POST | `/api/episodes/{id}/prepare` | Trigger on-demand remux, returns progress |\n| GET | `/api/episodes/watched` | All watched episodes with file info |\n| POST | `/api/metadata/fetch` | Trigger TMDB metadata refresh |\n\nAll error responses return JSON: `{\"error\": \"...\", \"code\": 404, \"detail\": null}`\n\n## Development\n\n```bash\n# Run server in development\ncd server\necho 'CAST_MEDIA_PATH=/path/to/media' \u003e .env\necho 'TMDB_API_KEY=your-key' \u003e\u003e .env\ncargo run\n\n# Run tests\ncargo test\n```\n\nThe tvOS app requires Xcode and an Apple Developer account. Build and deploy to your Apple TV over the same local network as the server.\n\n## Project Structure\n\n```\ncast/\n├── server/              # Rust media server (library crate + CLI binary)\n│   ├── src/\n│   │   ├── lib.rs       # Server library (start_server, AppState, background tasks)\n│   │   ├── main.rs      # CLI binary wrapper\n│   │   ├── library.rs   # Media directory scanner, filename parsing\n│   │   ├── db.rs        # SQLite (watch progress + metadata + credits cache)\n│   │   ├── routes.rs    # HTTP API endpoints\n│   │   ├── tmdb.rs      # TMDB API client + metadata fetching\n│   │   ├── media.rs     # ffprobe/ffmpeg integration\n│   │   └── mdns.rs      # Bonjour/mDNS advertisement\n│   └── Cargo.toml\n├── desktop/             # Tauri 2 desktop app\n│   ├── src-tauri/       # Rust backend (tray, commands, file ops)\n│   └── gui/             # HTML/CSS/JS frontend\n├── Cast/                # tvOS SwiftUI app (Xcode project)\n├── scripts/             # Windows install/uninstall scripts\n└── Cargo.toml           # Workspace root\n```\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedvin%2Fcast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedvin%2Fcast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedvin%2Fcast/lists"}