S3D Player: private video catalog on your web hosting
=====================================================

This package lets S3D Player users watch 3D videos stored on your own web
hosting by user name and password. You decide who can watch and who is
allowed to save videos. A dedicated server is not needed.

Files
-----
  config.php   your settings (the only file you need to edit)
  list.php     video list for the player (login and password)
  get.php      sends a video by a signed link, with seeking
  admin.php    admin panel: users and statistics (rename it, see step 4)
  common.php   common functions (internal)
  hash.php     password hash from the console (optional)
  .htaccess    closes internal files from the web
  media/       put your videos here (closed from the web)
  private/     service data: log, users, admin password hash (closed)

Requirements
------------
  * Web hosting with Apache 2.4 (.htaccess enabled) and HTTPS
  * PHP 7.3 or newer
  * Enough hosting traffic: every view streams the video from your hosting.
    For large libraries consider the Cloudflare R2 package instead.

Step 1. Upload the package
--------------------------
Copy all files and folders of this package into a folder on your hosting,
for example
  https://example.com/demo/
Make sure the .htaccess files are uploaded too (some FTP clients hide files
starting with a dot): one in the package folder, one in media/ and one in
private/.

Step 2. Upload videos
---------------------
Put your videos into media/ (mp4, mkv, avi, mov, m4v, m2ts, mts, ts, webm,
wmv, mpg). Subfolders are allowed.

The player detects the 3D format from the file name, so keep the usual
marks in the names, for example "Movie sbs.mp4" or "Movie_p.mkv".

Preview (optional): put an image with the same name next to the video,
for example "Movie sbs.jpg" (jpg, png or webp). Without an image the player
takes a frame from the video. The frame time can be set with a text file
"Movie sbs.thumb" containing a number of seconds.

You may keep the videos in another folder, also outside the site root:
set its full server path in S3D_FILES.

Step 3. Edit config.php
-----------------------
  S3D_SECRET       your own random string of 40 or more letters and digits
                   (use a password generator). Keep it private.
                   Until it is set the server answers "#error server not
                   configured".
  S3D_ADMIN_PASS   admin password for the first login
  S3D_ADMIN_FILE   admin page file name, see step 4
  S3D_FILES        only if the videos are not in media/

Leave the other values as they are.

Step 4. Admin panel
-------------------
Invent your own file name for the admin page, for example
"panel-7k2x.php" (letters, digits, "_" and "-", at least 6 characters).
Rename admin.php to this name and write the same name in S3D_ADMIN_FILE.
Under any other name, including admin.php, the page answers 404: this
hides it from people who scan sites for admin pages.

Open https://example.com/demo/panel-7k2x.php and log in with
S3D_ADMIN_PASS. Then:
  * check the "Server check" block: the number of videos found and that the
    folders are writable
  * set a new admin password (section "Admin password")
  * add users with passwords; choose "view only" or "save allowed"
  * delete or disable the demo user "demo-user" (password 12345)

"access on/off" blocks a user at once, including links issued earlier.
The panel also shows all videos on the server, who watched and saved what,
and failed logins by IP.

Forgot the admin password: delete private/admin.json via FTP; the password
from S3D_ADMIN_PASS works again.

Step 5. Test the server
-----------------------
In the Windows command prompt (replace the address, user and password):

  curl -i -X POST -d "user=demo-user&pass=12345" "https://example.com/demo/list.php"

  200 and "#private" on the first line   the server works
  403                                     wrong user or password, or not HTTPS
  429                                     too many wrong passwords, wait 15 min
  503 "#error server not configured"      S3D_SECRET is not set (step 3)

Step 6. Add the catalog to S3D Player
-------------------------------------
In S3D Player open the Media Manager (Catalog button), click "User" and add:

  [My videos]
  url      = https://example.com/demo/list.php
  user     = demo-user
  password = 12345

Save the file, select the source and click "Rescan".
Optional: "save_dir = D:\Video\Saved" sets where saved videos go.

How it works
------------
  * list.php checks the password and returns the video list with links
    signed for this user, valid for 12 hours (S3D_LINK_SEC).
  * get.php checks the signature and sends the file with Range support, so
    seeking works. Videos cannot be opened directly: media/ is closed.
  * "save allowed" only enables the Save option in the player. Anyone who
    can watch a video can technically record it; this is not DRM.

Service data (private/)
-----------------------
  access.log    log of logins, plays, saves and errors
  users.json    users (after the first change in the admin panel)
  admin.json    admin password hash
  fail_*.txt    failed login counters
All files are created with open permissions, so you can edit or delete
them by FTP. The folder is closed from the web by its .htaccess.

Troubleshooting
---------------
  Admin page answers 404
      the file name and S3D_ADMIN_FILE differ, or S3D_ADMIN_FILE is empty
  list.php answers 403 with the right password
      the site is opened by http, not https
  The list is empty
      no videos in media/ or PHP cannot read them: see "Server check"
      in the admin panel
  Videos open directly by URL
      the .htaccess in media/ is missing, or Apache ignores .htaccess
      (AllowOverride): ask the hosting support

Copyright (c) S3D Singapore, 2026, https://gradient-sg.com
