{"id":51118868,"url":"https://github.com/detain/phlix-windows-client","last_synced_at":"2026-06-28T02:01:04.477Z","repository":{"id":358162742,"uuid":"1240294922","full_name":"detain/phlix-windows-client","owner":"detain","description":"Windows desktop client for Phlix Media Server - Stream your media library to Windows PCs","archived":false,"fork":false,"pushed_at":"2026-06-21T21:16:07.000Z","size":4392,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-21T23:09:44.547Z","etag":null,"topics":["brightscript","dlna","electron-app","hls-streaming","home-media","htpc","jellyfin-alternative","media-player","media-server-client","mobile-app","phlix","plex-alternative","react-native","reactjs","samsung-tizen","smart-tv","streaming-client","tv-app","upnp","video-player"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/detain.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-16T01:16:43.000Z","updated_at":"2026-06-21T21:16:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/detain/phlix-windows-client","commit_stats":null,"previous_names":["detain/phlex-windows-client","detain/phlix-windows-client"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/detain/phlix-windows-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detain%2Fphlix-windows-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detain%2Fphlix-windows-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detain%2Fphlix-windows-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detain%2Fphlix-windows-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/detain","download_url":"https://codeload.github.com/detain/phlix-windows-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detain%2Fphlix-windows-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34755061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"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":["brightscript","dlna","electron-app","hls-streaming","home-media","htpc","jellyfin-alternative","media-player","media-server-client","mobile-app","phlix","plex-alternative","react-native","reactjs","samsung-tizen","smart-tv","streaming-client","tv-app","upnp","video-player"],"created_at":"2026-06-25T00:30:24.074Z","updated_at":"2026-06-28T02:01:04.466Z","avatar_url":"https://github.com/detain.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Phlix Windows Desktop App\n\n[![Build](https://github.com/detain/phlix-windows-client/actions/workflows/build.yml/badge.svg)](https://github.com/detain/phlix-windows-client/actions/workflows/build.yml)\n[![Test](https://github.com/detain/phlix-windows-client/actions/workflows/test.yml/badge.svg)](https://github.com/detain/phlix-windows-client/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/detain/phlix-windows-client/branch/master/graph/badge.svg)](https://codecov.io/gh/detain/phlix-windows-client)\n[![Node](https://img.shields.io/badge/node-%3E%3D22.12-339933?logo=node.js\u0026logoColor=white)](.github/workflows/test.yml)\n![Platform](https://img.shields.io/badge/platform-Windows%20x64-0078D6?logo=windows\u0026logoColor=white)\n\nA native Windows desktop application for the Phlix Media Server, built with Electron, Vue 3, and TypeScript. The user interface is provided by the shared **`@phlix/ui`** Vue app; this repo is a thin Electron shell + consumer.\n\n## Project Overview\n\nPhlix Windows provides a full-featured media server client for Windows, enabling users to browse, stream, and manage their media library with native desktop integration including system tray, media keys, and native menus. The entire renderer UI is the shared `@phlix/ui` app booted via `createPhlixApp(config)`, so screens and theming stay in sync with the other Phlix clients.\n\n## Features\n\n- **Media Library Browser** - Browse and search your media collection (provided by `@phlix/ui`)\n- **Video Player** - Full-featured video playback with controls\n- **System Tray Integration** - Minimize to tray with media controls\n- **Native Menus** - Full application menu with keyboard shortcuts\n- **Media Key Support** - Play/Pause, Stop, and Rewind/Fast-Forward (±10s) are bridged from the tray/menu into the player (Open File is temporarily a no-op, pending local-file support in the shared player)\n- **Authentication** - Secure login with session persistence (handled by `@phlix/ui`)\n- **Shared UI** - Modern Vue 3 interface from `@phlix/ui` with the Nocturne theme\n- **Settings Management** - Configurable preferences including minimize-to-tray behavior\n- **Hub Mode** - Connect to a Phlix Hub to manage multiple servers, with support for direct-LAN and relay connection modes\n\n\u003e **Temporarily dropped in the Vue migration:** the offline Downloads and realtime SyncPlay UIs were removed and will be re-added later as shared `@phlix/ui` seams.\n\n## Prerequisites\n\nBefore setting up the project, ensure you have the following installed:\n\n- **Node.js** v18.x or later (LTS recommended)\n- **npm** v9.x or later (comes with Node.js)\n- **Git** for version control\n- **Windows 10/11** as the target platform\n\nFor development:\n- **Visual Studio Code** (recommended) with extensions:\n  - ESLint\n  - Prettier\n  - TypeScript and related tools\n\n## Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/phlix/phlix-windows.git\n   cd phlix-windows\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Configure environment** (optional)\n\n   Create a `.env` file in the root directory if you need a custom default server URL (used as the\n   build-time fallback when no server URL is persisted and Hub mode is not configured):\n   ```\n   VITE_PHLIX_SERVER_URL=http://localhost:8096\n   ```\n\n## Configuration\n\nThe application stores configuration in the user's app data directory:\n- **Windows**: `%APPDATA%\\phlix-windows`\n\n### Configuration Options\n\n| Setting (electron-store key) | Default | Description |\n|---------|---------|-------------|\n| `minimizeToTray` | `true` | Minimize to system tray instead of closing |\n| `serverUrl` | (none) | Persisted direct media server URL (`app:get/set-server-url`) |\n| `deviceId` | Auto-generated | Stable per-install device id `windows-\u003cuuid\u003e` (`app:get-device-id`) |\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `VITE_PHLIX_SERVER_URL` | `http://localhost:8096` | Build-time fallback media server URL (used when no `serverUrl` is persisted and Hub mode is off) |\n| `NODE_ENV` | `development` | Runtime environment |\n\nHub mode is configured at runtime (persisted via `hub:set-config` in electron-store), not via an environment variable — see the Hub Mode section below.\n\n## Building the App\n\n### Development Mode\n\nRun the application in development mode with hot reload:\n\n```bash\nnpm run dev\n```\n\nThis starts:\n- Vite dev server on `http://localhost:5173`\n- Electron app with automatic reload on changes\n\n### Production Build\n\n**Build both renderer and main process:**\n```bash\nnpm run build\n```\n\n**Build only the renderer (Vue app):**\n```bash\nnpm run build:vite\n```\n\n**Build only the main process (Electron):**\n```bash\nnpm run build:electron\n```\n\n### Packaging\n\nPackage the app for Windows distribution:\n\n**NSIS Installer (recommended):**\n```bash\nnpm run package\n```\n\n**Windows Store (APPX):**\n```bash\nnpm run package:store\n```\n\nThe packaged output will be in the `release/` directory.\n\n## Testing\n\n### Running Tests\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests in watch mode\nnpm test -- --watch\n\n# Run tests with coverage\nnpm test -- --coverage\n```\n\n### Test Structure\n\n- Unit tests located in `tests/unit/` (22 tests): `resolveConfig.test.ts`, `electronBridge.test.ts`, `main.test.ts`\n- Test files use Vitest (`jsdom`, `@vitejs/plugin-vue`) with TypeScript\n- Coverage via `@vitest/coverage-v8`; the Electron `src/main/**` and `src/preload/**` glue is excluded\n\n### Linting \u0026 Typecheck\n\n```bash\n# Run ESLint (flat config: eslint.config.mjs)\nnpm run lint\n\n# Fix auto-fixable issues\nnpm run lint:fix\n\n# Typecheck the renderer (Vue) and the Electron main/preload\nnpx vue-tsc --noEmit\nnpx tsc -p tsconfig.main.json --noEmit\n```\n\n## Project Structure\n\n```\nphlix-windows/\n├── src/\n│   ├── main/           # Electron main process\n│   │   └── index.ts    # Main entry point, window management, IPC, tray\n│   ├── preload/        # Preload script (context bridge)\n│   │   └── index.ts    # Secure IPC exposure to renderer\n│   └── renderer/       # Thin @phlix/ui consumer (no local pages/components/stores)\n│       ├── main.ts            # Entry: boot() → createPhlixApp() → mount → installElectronBridge\n│       ├── resolveConfig.ts   # Pure app-mode + apiBase resolution (hub vs direct server)\n│       ├── electronBridge.ts  # Maps Electron media/window IPC → @phlix/ui player store + router\n│       ├── index.html         # Mounts #phlix-app\n│       ├── test-setup.ts      # jsdom localStorage mock\n│       ├── vite-env.d.ts\n│       └── types/electron.d.ts\n├── tests/\n│   └── unit/           # resolveConfig.test.ts · electronBridge.test.ts · main.test.ts (22 tests)\n├── build/              # Build resources (icons)\n├── release/            # Packaged application output (gitignored)\n├── package.json\n├── vite.config.mts\n├── vitest.config.mts\n├── eslint.config.mjs\n└── tsconfig.json\n```\n\n## Architecture\n\n### Electron Process Model\n\n1. **Main Process** (`src/main/index.ts`)\n   - Creates BrowserWindow\n   - Manages system tray and menus\n   - Handles IPC from renderer (incl. `app:get-server-url`/`app:set-server-url`/`app:get-device-id`)\n   - Manages app lifecycle\n\n2. **Preload Script** (`src/preload/index.ts`)\n   - Exposes safe APIs via contextBridge (incl. `getServerUrl`/`setServerUrl`/`getDeviceId`)\n   - Provides IPC invoke/send methods\n   - Relays media control events to the renderer\n\n3. **Renderer Process** (`src/renderer/`)\n   - A thin consumer of the shared `@phlix/ui` Vue app, booted via `createPhlixApp(config)`\n   - Vue 3 + Pinia + vue-router (peer deps of `@phlix/ui`)\n   - Pinned to `@phlix/ui` `#v0.51.0` and `@phlix/contracts` `#v0.1.1`\n   - Vite (`@vitejs/plugin-vue`) for development and bundling\n\n### UI \u0026 State\n\nAll screens, navigation, theming, and state live in the shared **`@phlix/ui`** app (Pinia stores + vue-router). This repo does not define its own pages, components, or stores. Configuration passed to `createPhlixApp` (app-mode, `apiBase`, `deviceHeaders`, theme, branding) is resolved at boot from Electron config; device headers are built with `@phlix/contracts` `buildPhlixHeaders`. Electron tray/menu events are bridged into `@phlix/ui`'s player store and router by `src/renderer/electronBridge.ts`.\n\n## Deployment\n\n### GitHub Actions CI/CD\n\nThe project uses GitHub Actions for continuous integration:\n\n- **test.yml** - Runs on every push/PR to validate code\n- **build.yml** - Creates releases on tags and publishes packages\n\n### Release Process\n\n1. Update version in `package.json`\n2. Create git tag:\n   ```bash\n   git tag -a v1.0.0 -m \"Release v1.0.0\"\n   git push origin v1.0.0\n   ```\n3. GitHub Actions will automatically:\n   - Run tests\n   - Build the application\n   - Create GitHub Release\n   - Upload artifacts\n\n### Windows Installer\n\nThe build workflow produces:\n- **NSIS Installer** - Traditional `.exe` installer\n- **APPX Package** - For Windows Store distribution\n\n## Hub Mode\n\nHub Mode allows you to connect to a Phlix Hub to manage and access multiple Phlix servers through a single interface. This is useful for users with servers in different locations or network environments.\n\n### Features\n\n- **Hub Authentication** - Sign in to your Phlix Hub account\n- **Server Switcher** - Quickly switch between your claimed servers\n- **Connection Modes**:\n  - **Direct** - Connect directly to servers via LAN for lowest latency\n  - **Relay** - Route traffic through the hub for remote access\n- **Session Persistence** - Hub session persists across app restarts\n\n### Configuration\n\nHub configuration is persisted at runtime in electron-store (via the `hub:set-config` IPC) — there is\nno environment variable for it. At boot, `resolveAppConfig` runs the app in **hub mode** (against\n`hub.hubUrl`) whenever a Hub URL is configured and the connection mode is not explicitly `direct`;\notherwise it runs in **server mode** against the persisted direct server URL.\n\n#### In-App Configuration\n1. Open Settings\n2. Navigate to Hub Mode section\n3. Enter your Hub URL\n4. Sign in with your Hub credentials\n5. Select a server from your claimed servers list\n6. Choose connection mode (Direct or Relay)\n\n### Connection Flow\n\n1. User configures Hub URL and signs in; the choice is persisted via `hub:set-config`\n2. On next boot, `resolveAppConfig` selects hub vs direct server mode and the `apiBase`\n3. App fetches the list of claimed servers from the Hub (via `@phlix/ui`)\n4. API calls route through direct-LAN or hub-relay based on the chosen mode\n5. Active server and connection mode persist across sessions\n\n## Troubleshooting\n\n### Common Issues\n\n**App doesn't start:**\n- Ensure Node.js 18+ is installed\n- Run `npm install` to install dependencies\n- Check console for error messages\n\n**Vite server port conflict:**\n- Kill processes using port 5173\n- Modify `vite.config.ts` to use a different port\n\n**Build fails with native modules:**\n- Run `npm rebuild` to rebuild native dependencies\n- Ensure electron-builder is up to date\n\n### Logs\n\nApplication logs are stored in:\n- **Windows**: `%APPDATA%\\phlix-windows\\logs\\`\n\nUse `electron-log` for runtime logging:\n```typescript\nimport log from 'electron-log';\nlog.info('Application started');\n```\n\n## License\n\nMIT License - see project repository for details.\n\n## Support\n\nFor issues and feature requests, please use the GitHub issue tracker.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdetain%2Fphlix-windows-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdetain%2Fphlix-windows-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdetain%2Fphlix-windows-client/lists"}