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)

./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):

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.