Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/detain/phlix-roku-client

Roku client for Phlix Media Server - Stream your media library to Roku devices
https://github.com/detain/phlix-roku-client

brightscript dlna electron-app hls-streaming home-media htpc jellyfin-alternative media-player media-server-client mobile-app plex-alternative react-native reactjs samsung-tizen smart-tv streaming-client tv-app upnp video-player

Last synced: 4 days ago
JSON representation

Roku client for Phlix Media Server - Stream your media library to Roku devices

Awesome Lists containing this project

README 

          
# Phlix Media Server - Roku Application



A native Roku application for the Phlix Media Server platform. Stream your media library with full playback control, seamless authentication, and progress synchronization.



## Features



- **Secure Authentication**: Device registration with token-based session management

- **Library Browsing**: Browse movies, TV shows, and collections with intuitive navigation

- **HLS Video Playback**: Stream video content with adaptive bitrate support

- **Full Remote Control**: Complete playback control via Roku remote (play, pause, seek, stop)

- **Progress Synchronization**: Track and sync watch progress across sessions

- **Multiple User Support**: Personalized libraries and watch states per user

- **Hub Mode**: Connect to a Phlix Hub for centralized authentication, server discovery, and relay-aware HLS playback through direct-LAN or hub-relay tunnel

- **Skip Intro/Outro**: Automatically displayed skip buttons when playback enters marker ranges defined by the server (intro start/end, outro start/end)

- **SyncPlay**: Watch with friends in perfect sync across multiple devices with NTP-style time synchronization, group state management, and synchronized playback controls (play/pause/seek)



## Prerequisites



### Required

- **Roku Device**: Any Roku device with developer mode enabled

- **Phlix Media Server**: Running instance accessible on your network

- **Roku Developer Account**: For sideloading apps



### Development Tools

- **Roku SDK**: For packaging and deployment ( rokupkg )

- **BrightScript Editor**: VS Code extension "BrightScript" by彩虹 (or any editor)

- **curl**: For direct device communication

- **zip**: For creating packages



### Network Requirements

- Roku device and Phlix Media Server on the same network

- Phlix Media Server API accessible from Roku device



## Installation



### 1. Enable Developer Mode on Roku



Press the following button sequence on your Roku remote:

1. Home (5 times)

2. Up (2 times)

3. Right (1 time)

4. Left (1 time)

5. Right (1 time)

6. Left (1 time)

7. Right (1 time)



Note the IP address shown and enable dev mode via the web interface at `http://`.



### 2. Clone and Configure



```bash

# Clone the repository

git clone https://github.com/your-org/phlix-roku.git

cd phlix-roku



# Review and update manifest if needed

# Edit: manifest title, version, icons

```



### 3. Install Dependencies



No external dependencies required. BrightScript is natively supported by Roku devices.



### 4. Configure Server Connection



The app will prompt for server URL on first launch, or you can pre-configure:



```bash

# Edit the default server URL in source/components/PhlixApp.brs

# Or set via Settings within the app

```



### 5. Hub Mode (Optional)



Hub Mode allows you to connect to a Phlix Hub for centralized authentication and multi-server access:



1. **Enable Hub Mode**: Go to Settings in the app

2. **Enter Hub URL**: Provide your hub server URL (e.g., `http://hub.example.com:8080`)

3. **Sign In**: Authenticate with your hub credentials

4. **Select Server**: Choose from your claimed servers

5. **Choose Connection Mode**:

   - **Direct**: Connect directly to server on LAN (fastest)

   - **Relay**: Route through hub tunnel (for remote access)



#### Hub Mode Storage Keys



| Key | Description |

|-----|-------------|

| `hub_url` | Hub server URL |

| `hub_session` | Hub authentication session (JWT tokens) |

| `active_server` | Currently selected server |

| `connection_mode` | "direct" or "relay" |



### 6. SyncPlay (Watch Together)



SyncPlay allows multiple users to watch the same content together remotely, staying in sync without manual timestamp coordination.



#### Features

- **NTP-Style Time Sync**: Weighted-mean offset calculation for accurate clock synchronization

- **Group Watching**: Create or join groups to watch with friends

- **Synchronized Playback**: Play, pause, and seek commands sync across all members

- **Member Presence**: See who's in the group and get notified on join/leave

- **Automatic Position Reports**: Periodic position updates every 30 seconds



#### Usage



1. **During Playback**: Press the SyncPlay button in the player overlay

2. **Create Group**: Tap "Create Group" to start a new SyncPlay session

3. **Join Group**: Enter a 6-character Group ID to join an existing session

4. **Watch Together**: All members receive synchronized play/pause/seek commands



#### SyncPlay WebSocket Events



| Event | Direction | Description |

|-------|-----------|-------------|

| `syncplay.join_group` | Client → Server | Join a SyncPlay group |

| `syncplay.leave_group` | Client → Server | Leave current group |

| `syncplay.playback_command` | Client → Server | Send play/pause/seek command |

| `syncplay.report_position` | Client → Server | Periodic position report |

| `syncplay.request_time_sync` | Client → Server | Request time synchronization |

| `syncplay.time_sync` | Server → Client | Time sync response (offset calculation) |

| `syncplay.group_state` | Server → Client | Current group state and members |

| `syncplay.playback_update` | Server → Client | Play/pause/seek from any member |

| `syncplay.member_joined` | Server → Client | New member joined group |

| `syncplay.member_left` | Server → Client | Member left group |



#### Time Synchronization Protocol



The client implements NTP-style time synchronization:

1. Client sends `syncplay.request_time_sync` with local timestamp

2. Server responds with `syncplay.time_sync` containing timestamps

3. Client computes: `offset = (server_time - client_send_time) + latency`

4. Rolling average of last 5 samples maintained for stability

5. `adjustedTime = Date.now() + averageOffset` used for position comparisons



## Configuration



### Environment Variables



| Variable | Description | Default |

|---------|-------------|---------|

| `ROKU_IP` | IP address of Roku device | `192.168.1.100` |

| `ROKU_DEV` | Developer username | `rokudev` |

| `ROKU_PASSWORD` | Developer password | `rokipassword` |



### Manifest Configuration



Edit `manifest` to customize:

- `title`: Application name

- `major_version`, `minor_version`, `build_version`: Version numbers

- `ui_resolutions`: Supported resolutions (hd, fhd, uhd)



### BrightScript Configuration



The app uses these configurable constants (in source files):



```brightscript

' In ApiClient.brs - Device capabilities

deviceProfile: {

    MaxStreamingBitrate: 30000000  ' 30 Mbps

    MaxStaticBitrate: 30000000

    SupportedMediaTypes: ["Video", "Audio"]

}

```



## Building the App



### Standard Build



```bash

# Create package for sideloading

make package



# This creates: phlix.zip

```



### Install to Device



```bash

# Install to configured Roku IP

make install ROKU_IP=192.168.1.100 ROKU_DEV=rokudev ROKU_PASSWORD=yourpass



# Or install with rokupkg

rokupkg --install phlix.zip

```



### Development Workflow



```bash

# 1. Make code changes

# 2. Package and install

make package install ROKU_IP=192.168.1.100



# 3. Launch app

make launch ROKU_IP=192.168.1.100



# 4. Debug via telnet on port 8080

telnet 192.168.1.100 8080

```



### Manual Deployment



```bash

# Create package manually

zip -r phlix.zip manifest source images



# Sideload via curl

curl -v -u rokudev:password -X POST \

    http://192.168.1.100:8060/install/app \

    -F "archive=@phlix.zip" \

    -F "manifest=@manifest"

```



## Testing



### Unit Tests



Unit tests are located in `tests/unit/` and use BrightScript's testing patterns.



```bash

# List available tests

make test



# Output shows:

# Found test: tests/unit/ApiClient.test.brs

# Found test: tests/unit/Storage.test.brs

# Found test: tests/unit/Utilities.test.brs

```



### Running Tests on Device



1. Deploy to device: `make install`

2. Tests run automatically via the test framework when accessed via developer portal



### Integration Tests



Integration tests in `tests/integration/` test API client against a live server.



```bash

# Run integration tests (requires running Phlix server)

# Deploy tests to device and run via developer portal

```



### Test Structure



```

tests/

├── unit/

│   ├── ApiClient.test.brs      # API client unit tests

│   ├── Storage.test.brs         # Storage unit tests

│   └── Utilities.test.brs       # Utilities unit tests

└── integration/

    └── ApiIntegration.test.brs  # API integration tests

```



## Deployment to Roku



### Pre-production Checklist



- [ ] Test on physical Roku device

- [ ] Verify all remote buttons work

- [ ] Check video playback with various formats

- [ ] Verify authentication flow

- [ ] Test library browsing

- [ ] Check network timeout handling

- [ ] Verify progress sync



### Publishing to Roku Channel Store



1. Create developer account at [developer.roku.com](https://developer.roku.com)

2. Sign in and go to Dashboard

3. Upload your packaged app (phlix.zip)

4. Complete store listing details

5. Submit for review



### Private Channel Testing



```bash

# Sideload directly for testing

make install



# Or use roku's dev channel mechanism

```



## API Endpoints



The app communicates with these Phlix API endpoints:



| Method | Endpoint | Description |

|--------|----------|-------------|

| POST | `/api/v1/Auth/Login` | User authentication with device info |

| DELETE | `/api/v1/Sessions/{id}` | End session |

| GET | `/api/v1/Sessions` | List active sessions |

| POST | `/api/v1/Sessions` | Create new session |

| GET | `/api/v1/Library/VirtualFolders` | Get library folders |

| GET | `/api/v1/Items` | Get items with filtering |

| GET | `/api/v1/Items/{id}` | Get single item details |

| GET | `/api/v1/Items/{id}/PlaybackInfo` | Get playback URLs and info |

| POST | `/api/v1/Sessions/Play` | Start playback session |

| POST | `/api/v1/Playstate` | Update playstate (play/pause/stop) |

| POST | `/api/v1/Playstate/Progress` | Report playback progress |

| POST | `/api/v1/Items/{id}/UserData` | Update user data (watched, etc.) |

| GET | `/api/v1/Users/Me` | Get current user info |



## Remote Control Reference



| Button | Action |

|--------|--------|

| Select/Play | Play / Pause toggle |

| Back | Go back / Close detail view |

| Left | Seek backward 30 seconds |

| Right | Seek forward 30 seconds |

| Rewind | Seek backward 10 seconds |

| Fast Forward | Seek forward 10 seconds |

| Options | Show/hide playback info |

| Skip Button | Skip intro/outro section (shown automatically during marker ranges) |



## Project Structure



```

phlix-roku/

├── source/

│   ├── main.brs                 # Main entry point

│   ├── lib/

│   │   ├── ApiClient.brs       # API client (communication layer)

│   │   ├── Storage.brs        # Persistent storage (registry)

│   │   ├── AuthManager.brs     # Authentication manager

│   │   ├── SessionManager.brs  # Session management

│   │   ├── LibraryManager.brs  # Library browsing logic

│   │   ├── TaskManager.brs     # Background task management

│   │   └── Utilities.brs        # Helper functions

│   ├── components/

│   │   ├── PhlixApp.brs       # Main app controller

│   │   ├── HomeScene.brs       # Home screen

│   │   ├── LibraryScene.brs    # Library browser

│   │   ├── DetailScene.brs     # Item detail view

│   │   ├── PlayerScene.brs     # Video player

│   │   ├── LoginScene.brs      # Login screen

│   │   └── GridItem.brs        # Grid item component

│   ├── player/

│   │   ├── HlsPlayer.brs       # HLS playback handler

│   │   └── SkipButton.brs      # Skip intro/outro button

│   ├── hub/

│   │   ├── HubAuth.brs         # Hub authentication

│   │   └── HubConfig.brs      # Hub configuration

│   ├── syncplay/

│   │   ├── SyncPlayTimeSync.brs # NTP-style time synchronization

│   │   └── SyncPlayService.brs  # SyncPlay WebSocket service

│   ├── pages/

│   │   ├── HomePage.brs        # Home page controller

│   │   ├── LibraryPage.brs      # Library page controller

│   │   └── SettingsPage.brs    # Settings page controller

│   └── data/

│       └── Theme.brs           # Theme constants

├── tests/

│   ├── unit/                   # Unit tests

│   ├── hub/                    # Hub mode tests

│   └── integration/            # Integration tests

├── images/                      # App icons and splash screens

├── manifest                    # App manifest

├── Makefile                    # Build automation

├── README.md                   # This file

└── DEVELOPER.md                # Developer documentation

```



## Troubleshooting



### App Won't Install



1. Verify Roku IP address is correct

2. Check developer credentials

3. Ensure dev mode is enabled on Roku

4. Try: `curl -u user:pass http://ROKU_IP:8060/` to verify connectivity



### API Connection Failed



1. Verify Phlix Media Server is running

2. Check network connectivity from Roku

3. Verify correct server URL in app settings

4. Check server logs for connection attempts



### Video Playback Issues



1. Verify HLS support on your server

2. Check network bandwidth

3. Try lower quality streams

4. Verify codec support (H.264/H.265 for video, AAC/AC3 for audio)



### Debugging



```bash

# Connect to Roku debug console

telnet ROKU_IP 8080



# Check app logs

# View variable values

# Step through BrightScript code

```



## Contributing



1. Fork the repository

2. Create a feature branch

3. Make changes with tests

4. Submit a pull request

5. Ensure CI passes



## License



MIT License - See LICENSE file for details



## Support



- Issue Tracker: GitHub Issues

- Documentation: [Phlix Wiki](https://github.com/your-org/phlix-roku/wiki)