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:

   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.

If no thumbnail image is uploaded, the add/edit forms can auto-grab one from the first supported source. YouTube and Dailymotion use direct thumbnail URLs; Vimeo, Wistia, TikTok, SoundCloud, and Spotify use oEmbed when available. Local uploaded videos can generate a first-frame thumbnail when ffmpeg is installed on the server.

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:

  <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