mediaplayer/README.md

# TyClifford.com — Media Player

A self-hosted multimedia player website built with PHP + SQLite + Video.js.
Styled to match the existing `gate.php` / `index.php` dark theme exactly.

---

## Requirements

- PHP 8.0+ with `pdo_sqlite`, `fileinfo` extensions
- Apache `mod_rewrite` for default pretty URLs, or switch to query URLs in Admin → Settings
- Write permissions on the `data/` and `media/` directories

---

## Installation

1. **Upload** all files to your web server. To use domain-level pretty URLs such as `/v/my-video`, deploy the app at the web root.

2. **Set permissions** so PHP can write to these directories:
   ```bash
   mkdir -p data media/videos media/thumbs
   chmod 755 data media media/videos media/thumbs
   ```

3. **Visit** `index.php` — the SQLite database is created automatically on first load.

4. **Log into admin** at `admin/login.php`
   - Default password: **`admin`**
   - ⚠️ Change it immediately in **Admin → Settings → Change Password**

---

## File Structure

```
/                        ← web root (deploy here)
├── index.php            ← Main player + catalogue (home page)
├── catalogue.php        ← Full video catalogue browse page
├── .htaccess            ← Pretty URL rewrite rules
├── includes/
│   ├── db.php           ← SQLite bootstrap + helper functions
│   └── layout.php       ← Shared HTML head, topbar, footer, pagination
├── admin/
│   ├── index.php        ← Video list with search + pagination
│   ├── add.php          ← Add new video with uploaded or external URL sources
│   ├── edit.php         ← Edit video metadata + manage local/remote sources
│   ├── youtube_import.php ← Scrape a YouTube channel and import videos
│   ├── settings.php     ← Site settings, per-page count, password
│   ├── login.php        ← Admin login
│   ├── logout.php       ← Session destroy + redirect
│   └── auth.php         ← Session auth helpers
├── media/               ← All media files (created automatically)
│   ├── videos/          ← Uploaded video files
│   └── thumbs/          ← Uploaded thumbnail images
└── data/
    └── media.db         ← SQLite database (auto-created)
```

---

## Usage

### Adding Videos (Admin)

1. Go to `admin/add.php`
2. Fill in title, description, duration, sort order
3. Upload a thumbnail (JPG/PNG/WebP)
4. Add one or more video sources. Each source can be either:
   - an uploaded local video file, stored under `media/videos/`
   - an external URL, stored in SQLite and played as a direct media source or provider embed
5. For uploaded files, supported formats include:
   - **MP4** (H.264) — widest compatibility
   - **WebM** (VP9) — smaller size, modern browsers
   - **OGV** — Firefox fallback (legacy)
6. Set quality labels (1080p, 720p, 480p, etc.)
7. Save — Video.js will use the stored source location and auto-select the best format the browser supports

External URLs must use `http://` or `https://`. Uploaded files and remote URLs can be mixed on the same video. Recognized provider URLs such as YouTube, Vimeo, Dailymotion, Twitch, Facebook, TikTok, Instagram, X/Twitter, SoundCloud, Spotify, Google Drive, Wistia, Streamable, and Loom render through their embed players.

### Importing YouTube Channels

Use **Admin → YouTube Importer** to paste a YouTube channel URL, `@handle`, or `UC...` channel ID. The importer scrapes the channel's `/videos` page, extracts video data from `ytInitialData`, previews the results, and imports selected videos as remote YouTube embed sources. Duplicate YouTube watch URLs are skipped.

### Public Search

The full catalogue page includes a public search for published videos only. Search matches video title, description, and slug; draft videos remain hidden.

### Public URLs

Pretty URLs are enabled by default:

- `/v/<slug>` plays a video
- `/all` lists all public videos
- `/search/<query>` searches public videos

You can switch to PHP query URLs in **Admin → Settings → Public URL Style** if your host does not support `.htaccess` rewrites.

### Catalogue Per-Page

Configurable in **Admin → Settings → Videos per page** (1–50).
The home page catalogue and the full catalogue page both respect this setting.

### Publishing

Videos can be toggled between **Published** and **Draft** from the admin list.
Only published videos appear on the public-facing pages.

### Sorting

Use the **Sort Order** field — lower numbers appear first. Default is 0.

---

## Player Features

- **Video.js 8.x** — responsive, accessible HTML5 player
- Custom skin matching the site's dark purple/green theme
- Playback rate controls: 0.5×, 1×, 1.25×, 1.5×, 2×
- Multiple source fallback — browser picks best format automatically
- Local uploaded sources and remote URL sources
- Provider embeds for popular video and audio platforms
- Thumbnail posters
- Keyboard accessible

---

## Security Notes

- Change the default admin password (`admin`) immediately after setup
- Consider adding `.htaccess` HTTP auth or IP restriction to `/admin/`
- The `data/` directory should not be web-accessible; add to `.htaccess`:
  ```apache
  <Directory data>
    Require all denied
  </Directory>
  ```
- For production, consider adding CSRF tokens to admin forms

---

## Customisation

- **Branding**: Edit site title/subtitle in Admin → Settings
- **Theme colours**: All CSS variables are in `includes/layout.php` `:root {}`
- **Social links**: Edit the About/Links cards in `index.php`