294 lines
5.2 KiB
Markdown
294 lines
5.2 KiB
Markdown
# FREAX Web Media Player
|
|
|
|
|
|
|
|
**FREAX** is a lightweight, self-hosted web media player built with PHP and FrankenPHP.
|
|
|
|
It is designed to be:
|
|
|
|
- Minimal
|
|
- Dependency-light
|
|
- Filesystem-native
|
|
- Streaming-friendly
|
|
- LAN-first with WAN support via HTTPS
|
|
|
|
FREAX intentionally avoids metadata scraping, database backends, and transcoding pipelines. It simply enumerates directories, validates media types, and streams files directly.
|
|
|
|
This makes it ideal for:
|
|
|
|
- Pre-encoded MP4 media libraries
|
|
- DVD rips
|
|
- YouTube archive collections
|
|
- Home NAS mounts
|
|
- CIFS / NFS mounted media shares
|
|
|
|
---
|
|
|
|
## Philosophy
|
|
|
|
FREAX follows classic Unix design principles:
|
|
|
|
- Use filesystem primitives
|
|
- Avoid unnecessary services
|
|
- Prefer explicit configuration
|
|
- No database dependency
|
|
- No background daemons
|
|
- No metadata scraping
|
|
- No automatic transcoding
|
|
|
|
If your files already play in a browser, FREAX will stream them.
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
### Server
|
|
|
|
- Linux (recommended)
|
|
- FrankenPHP
|
|
- PHP CLI or FrankenPHP php-cli (for password hashing)
|
|
- Bash (for startup script)
|
|
|
|
### Media Format
|
|
|
|
Recommended formats:
|
|
|
|
- MP4 (H.264 / H.265)
|
|
- AAC / MP3 audio
|
|
- Web-compatible containers
|
|
|
|
FREAX does **not** transcode. You should pre-encode media using tools such as:
|
|
|
|
- ffmpeg
|
|
- HandBrake
|
|
|
|
---
|
|
|
|
## Directory Layout
|
|
|
|
Your media root should contain:
|
|
|
|
```
|
|
|
|
MEDIA_ROOT/
|
|
├── Videos/
|
|
│ ├── TV/
|
|
│ └── Movies/
|
|
└── Music/
|
|
├── Artist/
|
|
└── Albums/
|
|
|
|
```
|
|
|
|
These are enumerated directly from disk.
|
|
|
|
No database indexing is used.
|
|
|
|
---
|
|
|
|
## Starting the Server
|
|
|
|
FREAX ships with a Bash launcher that:
|
|
|
|
- Sets credentials via environment variables
|
|
- Hashes passwords using bcrypt
|
|
- Starts FrankenPHP
|
|
- Avoids storing secrets on disk
|
|
|
|
### Script
|
|
|
|
Use:
|
|
|
|
```
|
|
|
|
start-media-server.sh
|
|
|
|
````
|
|
|
|
### Example (Prompt for Password)
|
|
|
|
```bash
|
|
./start-media-server.sh \
|
|
--user admin \
|
|
--prompt \
|
|
--media-root /mnt/media \
|
|
--port 9000
|
|
````
|
|
|
|
---
|
|
|
|
## Environment Variables
|
|
|
|
The launcher exports:
|
|
|
|
| Variable | Purpose |
|
|
| --------------- | -------------------------------------------- |
|
|
| MEDIA_USER | Login username |
|
|
| MEDIA_PASS_HASH | bcrypt password hash |
|
|
| MEDIA_ROOT | Base directory containing Videos/ and Music/ |
|
|
|
|
Credentials are **not stored on disk**.
|
|
|
|
They exist only in the running server environment.
|
|
|
|
---
|
|
|
|
## LAN Usage
|
|
|
|
For local network usage:
|
|
|
|
```
|
|
http://server-ip:9000
|
|
```
|
|
|
|
This works for testing and LAN streaming.
|
|
|
|
---
|
|
|
|
## WAN Usage (HTTPS Required)
|
|
|
|
When exposing FREAX over the internet, **HTTPS is mandatory**.
|
|
|
|
Authentication cookies are issued with:
|
|
|
|
* `'secure' => true`
|
|
* Scoped cookie path
|
|
|
|
Browsers will refuse to store session cookies over plain HTTP.
|
|
|
|
This prevents:
|
|
|
|
* Credential leakage
|
|
* Session hijacking
|
|
* Insecure deployments
|
|
|
|
This behavior is intentional.
|
|
|
|
---
|
|
|
|
## Reverse Proxy Example (Apache HTTPS)
|
|
|
|
If exposing FREAX publicly, terminate TLS at Apache (or another proxy/webserver):
|
|
|
|
```apache
|
|
ProxyPass /mediaserv/ http://youriphere:9000/
|
|
ProxyPassReverse /mediaserv/ http://youriphere:9000/
|
|
|
|
RequestHeader set X-Forwarded-Proto "https"
|
|
RequestHeader set X-Forwarded-Ssl on
|
|
```
|
|
|
|
This ensures:
|
|
|
|
* HTTPS detection works correctly
|
|
* Secure cookies are accepted
|
|
* Sessions persist properly
|
|
|
|
---
|
|
|
|
## Cookie Configuration
|
|
|
|
Cookie behavior is configured in:
|
|
|
|
```
|
|
auth.php
|
|
```
|
|
|
|
Defaults:
|
|
|
|
* Secure cookies enabled
|
|
* `/` cookie path
|
|
* Session-based authentication
|
|
|
|
You **can** disable secure cookies for LAN testing, but this is strongly discouraged for WAN deployments.
|
|
|
|
FREAX is secure-by-default.
|
|
|
|
---
|
|
|
|
## Playback Features
|
|
|
|
Current features:
|
|
|
|
* Folder-based browsing
|
|
* Automatic episode ordering
|
|
* Continuous playback (auto-play next file)
|
|
* HTML5 audio/video playback
|
|
* Lightweight UI
|
|
* Keyboard / remote-friendly controls
|
|
|
|
---
|
|
|
|
## Security Model
|
|
|
|
FREAX intentionally minimizes attack surface:
|
|
|
|
* No SQL backend
|
|
* No upload endpoints
|
|
* No file writes
|
|
* No user content creation
|
|
* No dynamic code execution
|
|
* Strict base directory enforcement
|
|
* MIME validation
|
|
* Extension filtering
|
|
* Realpath containment checks
|
|
|
|
Media access is read-only and authenticated.
|
|
|
|
---
|
|
|
|
## Why FREAX Instead of Plex/Jellyfin?
|
|
|
|
FREAX avoids:
|
|
|
|
* Metadata matching failures
|
|
* Transcoding overhead
|
|
* Database maintenance
|
|
* Framework dependency chains
|
|
* Heavy background services
|
|
* Cloud integration requirements
|
|
|
|
It is designed for users who:
|
|
|
|
* Control their own encoding pipeline
|
|
* Understand filesystem mounts
|
|
* Want predictable behavior
|
|
* Prefer minimal infrastructure
|
|
|
|
---
|
|
|
|
## Name Origin
|
|
|
|
**FREAX** is a playful nod to:
|
|
|
|
* Linus Torvalds' original Linux codename ("Freax")
|
|
* "Free" software philosophy
|
|
* A lightweight alternative to Plex-style platforms
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Open source.
|
|
|
|
Use it, fork it, modify it, self-host it.
|
|
|
|
---
|
|
|
|
## Disclaimer
|
|
|
|
FREAX is intended for personal media servers.
|
|
|
|
You are responsible for:
|
|
|
|
* Network exposure
|
|
* Firewall rules
|
|
* TLS configuration
|
|
* Legal compliance for your hosted media, this isn't a piracy site kit, so don't ask for help for that.
|
|
|
|
This is free software released under the GPLv2 license. You have permission to make open source forks as long as it stays open source.
|
|
|
|
---
|
|
|
|
Happy hacking.
|
|
|