PlayHub Documentation

What PlayHub includes

PlayHub is a self-hosted product for publishing on-demand video, running creator channels and communities, hosting real-time rooms, recording replays, monetizing engagement, and administering the complete service from one dashboard.

What's new in PlayHub 0.9.13

Version 0.9.13 follows 0.9.12 and updates playback, private cloud delivery, Shorts, responsive layouts, branding, signup roles, and content administration. The web version, native app build number, and API contract version have independent histories. See the React Native application guide for Android and iOS.

Playback startup, retry, and adaptive imports

• Early Play clicks: Watch and standalone embeds use the native media element when it can buffer, or wait for the provider's readiness event. Pending playback has a bounded wait and is cancelled when paused or removed during navigation.
• Recovery: retry reloads failed media and can restore its previous position. Persistent playback checks that its player is still connected. Unavailable origins, expired links, unsupported formats, and autoplay denial still need a meaningful user action.
• Player CORS: website and embed players omit unnecessary anonymous crossOrigin attributes. Remote JavaScript HLS/DASH manifests, segments, and captions still need their own valid origin headers.
• Canonical direct imports: direct HLS imports on the site's bare or www hostname use the canonical HTTPS origin in APP_URL; the original saved import URL remains unchanged. Other domains, unrelated subdomains, credential-bearing URLs, and unrelated explicit ports are excluded.
• Correct source types: MIME detection reads the URL path independently of query strings and fragments, so signed .m3u8 URLs retain HLS classification. Watch, persistent playback, and embeds let HLS/DASH providers determine live, DVR, or on-demand status; ordinary files remain on demand.
• Import serialization: a direct import exposes its actual media source rather than an uploaded-file route. Upload processing still generates progressive MP4 renditions; this update adds no automatic HLS/DASH transcoding, DRM, or HDR packaging.

Private and paid video protection

Media requests retain resource-specific authorization and expiring playback links. Authorized owners and administrators can receive signed viewer claims for media requests that cannot attach the website bearer token. Delivery rechecks current access, account restrictions, and private-profile ownership. Cloud playback authorizes the application request before redirecting to a bounded provider-signed URL; protected redirects use private, non-storable headers and cannot outlive the incoming application signature. Private objects have no public-CDN fallback when signing fails. Local delivery preserves byte ranges for seeking.

Shorts classification and discovery fixes

• Ordinary uploaded videos with measured durations from 1 through 60 seconds become Shorts, including older records saved with a default standard-video flag. Processing checks duration again; automatic classification does not require portrait dimensions.
• The explicit Upload Short flow still requires a portrait ratio from 0.45 through 0.8 and a maximum duration of 60 seconds.
• Shorts disable incompatible video ads and chapters. Sale-enabled clips explicitly classified as standard videos stay standard to preserve buyer access. Provider imports retain provider classification, and live replays remain replays.
• Discovery and returned resources apply the same classification rules. Trending tags sum actual views_count values from the loaded feed, deduplicate case variants and repeated/hash-prefixed tags per video, and rank by views. These are feed totals; no synthetic multiplier, fallback tags, or site-wide aggregate is added.
• Uploader names and avatars open the correct channel using shared profile navigation. Follow remains a separate action. Missing destinations are disabled, with keyboard focus and narrow-screen styling.

Comments, navigation, and content layouts

Mobile comment menus now render as scrollable sheets in the document body, keeping Delete reachable. Delete and report confirmations render above Shorts overlays. Delete remains permission-controlled and explains that deleting a parent removes its replies.

Opening or dragging the mobile sidebar restores the header and positions the drawer beneath its 64-pixel top bar. Dynamic viewport height and safe-area padding remove the gap caused by a hidden header. Small-screen headers and information pages wrap long content.

Creator Studio content tables reserve room before showing the summary rail. Intermediate widths scroll inside the table container; narrow screens show labeled cards with selection, metrics, and row actions. Admin content receives corresponding mobile selection and overflow fixes.

Branding, signup roles, and administrator actions

Cloud display images and fewer provider requests

Private cloud avatars and banners now use the application's signed /media/images route when no explicit public base URL is configured. User Settings and channel profiles preserve complete API avatar_url and cover_url signatures instead of reconstructing unsigned upload paths. Local editing previews retain priority.

Display links last six hours and accept only approved raster paths under avatars, covers, branding, logos, banners, gifts, and stickers. Signature validation happens before reading the private cache. Protected video thumbnails and community, comment, and message images retain their own access routes.

Oversized, malformed, HTML, and SVG objects are rejected. Successful application overwrites/deletions invalidate cache entries; failed remote changes keep the previous entry usable. Provider-side changes may remain cached until expiry or deliberate maintenance.

Shared API, push, and Live updates

The shared backend exposes API v1 for native bootstrap, authentication, refresh, TV pairing, playback, resumable uploads, progress, and notifications. The website continues using its versionless API. Native direct-to-cloud multipart upload is not implemented.

FCM and APNs delivery now includes a durable outbox, queue dispatch, bounded retries, recovery, and registration/preference checks. Delivery defaults to disabled. Bootstrap enables it only with platform credentials and required tables ready. Supervise a worker for the configured push queue (default push); the ordinary videos,default worker does not consume it. Registration success alone does not prove device delivery.

The 9 October connected Android Live pass covers bidirectional real media, supported interaction and moderation, token revocation, recording, and physical replay playback against a local HTTPS backend. It supersedes the earlier blocked milestone notes. Fixes include starting an unchanged saved schedule after its due time, deterministic chat order with equal timestamps, clearing stale ended-summary errors, and reconciling abnormal host loss. See native Live setup and acceptance.

This is scoped development-device acceptance, with a 2,000 ms owner-selected latency gate. It does not establish production acceptance, iOS readiness, all Android GPUs, locked camera FPS, or release-build memory behavior. TURN UDP passed; TURN TCP/TLS were not configured, and optional RTMP ingress was not rerun.

Features retained from previous releases

Persistent and scroll miniplayers, standalone embeds, captions and chapters, provider imports, analytics/CSV exports, VAST and Google IMA, paid videos and community photo sets, wallet tips, boosts, creator earnings, withdrawal review, localized SEO/pages/email templates, plugin management, and transactional updates remain available from the 0.9.9–0.9.12 baseline. Review every documented web version below.

Upgrade and configure 0.9.13

Use the distribution's supported update path and a matching application, locked dependency set, frontend manifest/assets, and database state. The historical 0.7.5 → 0.9.9 manual package has its own guarded procedure and is not a 0.9.13 updater.

1. Verify recoverable backups of the database, media, environment, administrative settings, and previous deployable release. Preserve customer secrets and storage configuration.
2. Deploy matching PHP source, locked Composer dependencies, migrations, and frontend release metadata on PHP 8.3+. React 19, Vite 7, and Vidstack 1.15 are the current web toolchain; choose the Node runtime required by its lockfile.
3. For a source deployment, run the build commands below in the web application root. Deploy the complete build/ output and manifest together, with the configured /build/ base. Retain older chunks while open tabs can still request them.
4. Apply the release's required migrations through the supported deployment process, refresh caches, and restart supervised workers after active jobs finish. Keep the videos,default worker and Laravel scheduler running; image-cache pruning depends on the scheduler.
5. Allow writes to private image-cache and media staging directories with enough local disk. Keep those cache files private and preserve protected media routes.
6. Set APP_URL to the actual canonical HTTPS origin. Test direct-import manifests and relative segments there; configure remote adaptive-source CORS for each required origin.
7. Review the provider-specific storage requirements, resolve any exhausted transaction cap, and test the intended account. Connection testing performs real write/read/delete operations and does not save settings.
8. If enabling native push, configure the platform credentials and outbox tables, then supervise the configured push queue. Complete native signing/device delivery separately from the web update.

npm ci
npm run build

Acceptance after deployment

• Verify authorized and unauthorized private-video requests, expiration, seeking, and paid access.
• Check a cold display image, a warm image, and an ETag / Last-Modified conditional response.
• Play a direct HLS import in Watch and an embed at the canonical hostname; check segments and captions.
• Upload a disposable short clip; verify classification, discovery, and seeking.
• Change a test account role, refresh, and compare displayed role and effective permissions.
• Delete a disposable category and confirm its videos remain available as Uncategorized.
• Exercise comment menus, confirmations, the mobile drawer, Creator Studio cards, and Admin selection on narrow screens.
• Verify queues, the scheduler, real storage uploads, processing, playback, deletion, Live recording, and replay on the actual deployment.

The source records earlier isolated regression/build/browser checks; they do not validate a customer's credentials, cap, origin configuration, services, or deployment. Record the real deployment date and acceptance result. Rollback restores a coherent application/frontend/database release while preserving media and customer configuration.

Web version history

Version 0.9.13 is documented above. The entries below preserve the existing published web release history. Native development milestones have their own application history.

Version 0.9.9 operations guide

Version 0.9.9 adds an extension platform, transactional updates, new paid-content workflows, persistent playback, deeper discovery, and expanded administration. Use this section as the operating reference for capabilities introduced in this release.

Plugins and system updates

Install extensions only from a source you trust. Plugin packages and system updates execute server-side code, so review compatibility, dependencies, requested configuration, and the package source before enabling them.

Direct update from 0.7.5

The packaged Update_v0.9.9 manual update upgrades a verified PlayHub 0.7.5 installation directly to 0.9.9; the 0.7.6 and 0.7.7 packages are not required. Do not use this package on an older release. Run the update as the operating-system user that owns PlayHub and stop uploads, streams, queue jobs, and other writes first.

• Verify restorable backups of the complete application, .env, database, uploads/, storage/, media, branding, plugins, and service configuration.
• From the PlayHub root, enable maintenance mode with php artisan down --retry=60.
• Upload the contents of Update_v0.9.9/ into the existing root. Preserve customer environment files, runtime data, uploads, media, plugins, SSL files, and active server configuration.
• Do not run npm install, npm run build, composer install, or composer update. The production build is included and the Composer lock is unchanged.
• Run the guarded database updater below. It verifies the 0.7.5 baseline, approved migration checksums, schema conflicts, and protected table row counts before applying changes.
• Refresh caches, restart long-running application workers, disable maintenance mode, then verify VERSION, /api/health, core pages, existing data, Plugins, queues, and real-time notifications.

php update_database.php

Only after the database updater reports success, remove it from the public root and finish deployment:

rm update_database.php
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan queue:restart
php artisan reverb:restart
php artisan up

If the Artisan Reverb restart command is unavailable, restart Reverb with the installation's existing supervisor or service manager before leaving maintenance mode. LiveKit does not need a restart for this file and database update unless its service configuration also changed.

Developing plugins

Use the dedicated Plugin development guide to create a Plugin API v1 package from an empty directory, add backend and browser integrations, package it safely, and test its complete lifecycle.

Playback, discovery, and video presentation

Monetization and creator revenue

Video advertising now supports VAST pre-roll, timed mid-roll, and post-roll breaks. Creator video payouts use completed VAST impressions with the VAST CPM or administrator fallback CPM, a configurable creator percentage, fractional accrual, self-view exclusion, hourly deduplication, and idempotent wallet crediting. Shorts cannot be sold as paid videos and are excluded from the standard player's Up Next and autoplay sequence.

Community, creator, and publishing workflows

Administration, localization, and delivery

Upgrade behavior and removed controls

• System Settings now uses section navigation and persists changes only when Save is selected.
• Fresh visitors and new accounts start in light theme; existing saved preferences remain unchanged.
• The mobile header and bottom navigator coordinate hide/reveal behavior based on scroll direction.
• The account menu uses full-width rows and displays the selected-currency wallet balance.
• Legacy violet accents now follow the active UI accent color.
• The video-player context menu uses the updated translucent compact design and accent rail.
• Admin Dashboard and Earnings typography is larger for compact interfaces and transaction details.
• Shared previews use a centered white play indicator on a translucent black circle.
• Comment deletion and reporting now require confirmation in viewer, Creator Studio, and moderation workflows.
• New local and imported videos require an explicit category instead of preselecting the first category.
• YouTube imports preserve descriptions, move description hashtags into Tags, and fall back to current first-party player metadata for tags and chapters.
• Temporary S3 links refresh correctly, while iPhone playback prioritizes compatible renditions and supports Safari byte ranges.
• Route loading keeps the current page visible and reaches 100% before replacing it with ready destination content.

Version 0.9.9 removes the unlicensed LightGallery dependency in favor of PlayHub's native responsive image viewer. It also removes the mobile-header theme switcher, duplicate header Go Live action, sidebar user summary card, obsolete System Settings collapse control, and setup's Product license heading and instructional paragraph. License verification remains required.

Develop a PlayHub plugin from scratch

PlayHub Plugin API v1 lets an extension add Laravel services, routes, migrations, settings, server hooks, browser hooks, website pages, and Admin workspaces without changing PlayHub core files. This guide builds a small but complete acme.example-tools plugin and explains how each part is loaded.

1. Prepare the development environment

• Use a staging PlayHub 0.9.9 or newer installation with PHP 8.3 or newer and the PHP ZIP extension.
• Keep the plugin in its own source directory and source-control repository; do not develop by editing PlayHub core files.
• Choose a globally unique lowercase plugin ID such as acme.example-tools and a matching PHP namespace such as Acme\ExampleTools.
• Decide whether the plugin needs a backend provider, database tables, settings, browser assets, a website page, an Admin workspace, or only a subset.
• Use a staging database and take a backup before testing migrations or uninstall behavior.
• Plan authorization for every endpoint. A hidden Admin navigation link is not a server-side permission check.

2. Create the package structure

Create the following directory tree. Only plugin.json is always required; the other paths are included when declared by the manifest or used by the plugin.

acme.example-tools/
├── plugin.json
├── README.md
├── CHANGELOG.md
├── src/
│   ├── PluginServiceProvider.php
│   └── Lifecycle.php
├── routes/
│   └── api.php
├── database/
│   └── migrations/
│       └── 2026_09_06_000000_create_example_tools_notes.php
└── assets/
    ├── example-tools.js
    └── example-tools.css

Namespace classes, routes, tables, cache keys, browser globals, and CSS classes with the vendor and plugin name. This prevents collisions with PlayHub and other extensions.

3. Write the plugin manifest

Place plugin.json at the package root. Provider and lifecycle classes must be covered by the declared PSR-4 namespace. Paths use forward slashes and must remain inside the package.

{
  "id": "acme.example-tools",
  "name": "Example Tools",
  "version": "1.0.0",
  "api": 1,
  "description": "A complete PlayHub Plugin API v1 example.",
  "homepage": "https://example.com/playhub-plugins/example-tools",
  "author": {
    "name": "Acme",
    "url": "https://example.com"
  },
  "requires": {
    "playhub": ">=0.9.9",
    "php": ">=8.3.0",
    "extensions": ["json"]
  },
  "dependencies": {},
  "autoload": {
    "psr-4": {
      "Acme\\ExampleTools\\": "src/"
    }
  },
  "providers": [
    "Acme\\ExampleTools\\PluginServiceProvider"
  ],
  "lifecycle": "Acme\\ExampleTools\\Lifecycle",
  "migrations": "database/migrations",
  "assets": {
    "styles": ["assets/example-tools.css"],
    "scripts": ["assets/example-tools.js"]
  },
  "settings": [
    {
      "key": "greeting",
      "label": "Greeting",
      "type": "text",
      "description": "Text displayed by the example pages.",
      "default": "Hello from Example Tools",
      "required": true,
      "public": true,
      "max_length": 120
    },
    {
      "key": "api_token",
      "label": "External API token",
      "type": "password",
      "description": "Optional private credential used only on the server.",
      "required": false,
      "public": false
    }
  ],
  "capabilities": [
    "Example website page",
    "Example Admin workspace",
    "Backend status endpoint"
  ]
}

Manifest field reference

4. Create the service provider

Extend PlayHub's plugin provider, return the exact manifest ID, and use the plugin context for package paths, settings, actions, and filters. Register container bindings in register(); load routes and hooks in boot().

<?php

namespace Acme\ExampleTools;

use App\Plugins\PluginServiceProvider as PlayHubPluginServiceProvider;
use Illuminate\Support\Facades\Route;

final class PluginServiceProvider extends PlayHubPluginServiceProvider
{
    protected function pluginId(): string
    {
        return 'acme.example-tools';
    }

    public function boot(): void
    {
        $context = $this->plugin();

        Route::prefix('api/example-tools')
            ->group($context->path('routes/api.php'));

        $context->addFilter(
            'playhub.public_settings',
            function (array $settings) use ($context): array {
                $settings['example_tools'] = [
                    'greeting' => $context->setting(
                        'greeting',
                        'Hello from Example Tools'
                    ),
                ];

                return $settings;
            }
        );
    }
}

The provider is instantiated only for an enabled, compatible plugin. A provider exception disables that plugin's runtime contribution and is recorded in Admin Plugins. Do not perform slow remote requests during application bootstrap.

PluginContext methods

5. Add routes and authorize them

The provider above adds an /api/example-tools prefix. This read-only status route can be public. Any endpoint that reads private data or changes state must use auth:sanctum, validate its request, authorize the user in a controller or policy, and apply an appropriate throttle.

<?php

use Illuminate\Support\Facades\Route;

Route::get('/status', static fn () => response()
    ->json([
        'ok' => true,
        'plugin' => 'acme.example-tools',
        'version' => '1.0.0',
    ])
    ->header('Cache-Control', 'no-store'))
    ->middleware('throttle:60,1');

6. Add database migrations when needed

Use a plugin-specific table prefix and a globally unique migration filename. Add a new migration for every released schema change; never edit a migration that customers may already have run.

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('example_tools_notes', function (Blueprint $table): void {
            $table->id();
            $table->foreignId('user_id')->index();
            $table->string('title', 160);
            $table->text('body')->nullable();
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('example_tools_notes');
    }
};

PlayHub runs declared pending migrations with --force while enabling the plugin. Disabling or removing a plugin does not automatically roll migrations back. Preserve customer data by default; if uninstall should remove owned tables, implement that decision explicitly and disclose it to administrators.

7. Implement lifecycle behavior

The lifecycle class is resolved through Laravel's container. Each method is optional. Keep enable and settings-update operations repeatable, avoid logging credentials, and leave the application consistent if an exception occurs.

<?php

namespace Acme\ExampleTools;

use App\Plugins\PluginContext;
use App\Plugins\PluginLifecycle;

final class Lifecycle extends PluginLifecycle
{
    public function enable(PluginContext $context): void
    {
        logger()->info('Example Tools enabled.', [
            'plugin' => $context->id(),
            'version' => $context->version(),
        ]);
    }

    public function disable(PluginContext $context): void
    {
        logger()->info('Example Tools disabled.');
    }

    public function settingsUpdated(
        PluginContext $context,
        array $previousSettings
    ): void {
        logger()->info('Example Tools settings updated.');
    }

    public function uninstall(PluginContext $context): void
    {
        // Remove only plugin-owned data that the administrator expects to lose.
    }
}

8. Add browser assets and pages

Declared scripts load through PlayHub's protected asset route. Register with the exact plugin ID. A website page receives request, navigate, and user tools. An Admin workspace also receives PlayHub confirm and alert dialogs.

const PLUGIN_ID = 'acme.example-tools';

function mountExample(container, tools, greeting) {
  const controller = new AbortController();
  const section = document.createElement('section');
  section.className = 'example-tools';

  const title = document.createElement('h2');
  title.textContent = greeting;
  const status = document.createElement('p');
  status.textContent = 'Checking the plugin API...';
  section.append(title, status);
  container.replaceChildren(section);

  tools.request('/example-tools/status', {
    signal: controller.signal,
    trackPageLoading: false,
  }).then((payload) => {
    status.textContent = payload.ok
      ? `Plugin ${payload.version} is ready.`
      : 'The plugin API reported a problem.';
  }).catch((error) => {
    if (error.name !== 'AbortError') {
      status.textContent = error.message || 'The plugin API is unavailable.';
    }
  });

  return () => {
    controller.abort();
    container.replaceChildren();
  };
}

window.PlayHub.register(PLUGIN_ID, (plugin) => {
  const greeting = String(
    plugin.settings.greeting || 'Hello from Example Tools'
  );

  plugin.registerPage({
    path: '/example-tools',
    authRequired: false,
    mount: (container, tools) =>
      mountExample(container, tools, greeting),
  });

  plugin.registerAdminPage({
    path: `/admin/extensions/${PLUGIN_ID}`,
    label: 'Example Tools',
    title: 'Example Tools',
    subtitle: 'Verify the example plugin runtime and API.',
    icon: 'plugin',
    mount: (container, tools) =>
      mountExample(container, tools, greeting),
  });
});

.example-tools {
  max-width: 760px;
  padding: 24px;
  border: 1px solid var(--line, #dfe3ea);
  border-radius: 8px;
  background: var(--surface, #fff);
}

.example-tools h2 {
  margin: 0 0 8px;
}

.example-tools p {
  margin: 0;
}

The mount function must return cleanup when it creates listeners, timers, observers, requests, or external DOM. PlayHub calls cleanup during route changes and Admin workspace unmounting. Use the provided navigation and request tools so authentication, language headers, and route loading remain integrated.

Browser Plugin API v1

9. Configure settings correctly

All plugin settings are encrypted at rest. The public flag controls whether a value is also sent to the browser, not whether it is stored encrypted. Keep public false unless frontend code genuinely needs the value; password fields can never be public.

A required field without a usable default must be configured in Admin Plugins before the plugin can be enabled. Server code reads every setting through PluginContext; browser code receives only public settings.

10. Use actions and filters safely

Actions announce an event and are appropriate for side effects. Filters receive a value and must return the value that the next listener should receive. Hook names start with a lowercase letter and may contain lowercase letters, numbers, dots, colons, dashes, and underscores. Priorities range from -1000 to 1000; lower values run first and equal priorities keep registration order.

Prefix custom hooks with the plugin ID, for example acme.example-tools.note.created. Catch expected integration failures inside the plugin and preserve the documented input and output type of every core filter.

11. Validate and package the ZIP

Validate JSON and PHP syntax before packaging. The example below creates a ZIP whose root contains plugin.json; one wrapper directory is also accepted.

php -r 'json_decode(file_get_contents("plugin.json"), true, 64, JSON_THROW_ON_ERROR); echo "Manifest JSON is valid.\n";'
find . -name '*.php' -print0 | xargs -0 -n1 php -l
zip -r ../acme.example-tools-1.0.0.zip . -x '*.DS_Store' '.git/*'

• The default maximum ZIP size is 25 MB, with up to 2,000 entries, 100 MB uncompressed, and 20 MB per file.
• Do not include symlinks, traversal paths, absolute paths, duplicate paths, .env, .htaccess, .user.ini, or web.config.
• Every PSR-4 directory, migration directory, and declared asset must exist in the package.
• Declare browser assets explicitly. Supported delivered files include CSS, JS, MJS, common web images, fonts, JSON, and WebAssembly.
• Exclude development artifacts such as .git/, node_modules/, tests, source maps, and unneeded vendor files. Package only reviewed runtime files you may redistribute.
• Include a README, changelog, license information, configuration instructions, and destructive-uninstall warning when applicable.

12. Install and test the plugin

Release and update workflow

1. Increase the semantic version in plugin.json and update the changelog.
2. Add new migrations for schema changes and preserve existing setting keys whenever possible.
3. Test a fresh installation and an update from every supported previous plugin version.
4. Disable the installed plugin before uploading the replacement ZIP. The manifest ID must remain unchanged.
5. Review preserved settings, enable the new package, verify migrations, and test all backend and browser surfaces again.

PlayHub creates a rollback-safe package replacement during installation, but plugin migrations and external side effects still require the plugin author's own forward-compatible design. An enabled dependent plugin prevents its required dependency from being disabled or removed.

Pre-release checklist

• The manifest ID, provider ID, browser registration ID, and package identity match exactly.
• All PHP files pass syntax checks and every manifest class is covered by PSR-4.
• Fresh enable, repeated enable, disable, settings update, package update, and uninstall behavior are tested.
• Routes validate input, authenticate callers, authorize resources, throttle abuse, and never return secrets.
• Migrations use plugin-owned names, preserve existing data, and support upgrades from released versions.
• Browser mounts clean up requests, timers, observers, event listeners, and inserted DOM.
• Public settings and logs contain no credentials, tokens, personal data, or private configuration.
• The plugin works in light and dark themes, narrow mobile layouts, and the supported browsers.
• The ZIP installs through Admin Plugins without manual file edits or core modifications.

Common development errors

Server requirements

Use a VPS or dedicated server where you control PHP-FPM, background services, firewall rules, Docker, and process supervision. Shared hosting is suitable only when it exposes every requirement below.

Required software

PHP extensions and functions

bcmath ctype curl dom fileinfo filter gd intl json mbstring openssl
pdo pdo_mysql session tokenizer xml zip zlib

Imagick is recommended for improved image processing. The PHP-FPM user also needs access to exec(), proc_open(), and nohup so the installer can stream process output and start its temporary installation worker.

Capacity and access

• At least 256 MB PHP memory; 512 MB is preferable for installation.
• At least 2 GB free for installation and 10 GB before accepting media.
• Writable storage/, bootstrap/cache/, uploads/, and lang/.
• Temporary root write access for .env, node_modules/, and build/.
• Outbound HTTPS to npm and the PlayHub license verification service.
• Supervisor or systemd access for the queue worker and runtime manager.
• Cron access for the Laravel scheduler.
• Root or sudo access for the LiveKit Docker runtime installation.

Package contents

Upload the complete package and preserve hidden files. The web installer generates environment-specific dependencies and production assets on the destination server.

Generated during installation

Install PlayHub

Prepare the domain and services before opening the installer. The installation process verifies the same critical dependencies again before writing production state.

1. Prepare the domain and database

2. Upload and set ownership

sudo chown -R <web-user>:<web-group> /var/www/playhub
sudo find /var/www/playhub/storage /var/www/playhub/bootstrap/cache /var/www/playhub/uploads -type d -exec chmod 775 {} \;
sudo find /var/www/playhub/storage /var/www/playhub/bootstrap/cache /var/www/playhub/uploads -type f -exec chmod 664 {} \;

3. Configure the web server

Nginx

Use server-configs/nginx-root-install.conf inside the domain's existing server {} block. Keep the root pointed at the package directory, update fastcgi_pass for the installed PHP 8.3 socket, then validate and reload Nginx.

sudo nginx -t
sudo systemctl reload nginx

Apache

Enable mod_rewrite, allow .htaccess overrides for the domain, and use server-configs/apache-vhost-example.conf as the virtual host reference. Preserve the root .htaccess file.

4. Complete the four-step installer

Open https://your-domain.com/install.php.

Keep the installation page open during Step 3. The console intentionally hides passwords, tokens, and service secrets.

5. Complete the production checklist

• Open the website and sign in with the owner account.
• Open /admin and review Website Configuration and System Settings.
• Configure SMTP or SendGrid and send a test message.
• Start the persistent queue worker and scheduler.
• Run the LiveKit runtime installer and test browser plus RTMP streaming.
• Configure and test local or cloud media storage.
• Configure Stripe or PayPal before enabling wallet payments.
• Run an upload, thumbnail, playback, live recording, and replay test.
• Configure an automatic backup and test one manual backup.
• Remove install.php after installation if your deployment policy requires it.

Core background services

The web request process must remain short. Video processing, replay finalization, notifications, scheduled publishing, retention, and backups run through queues and the scheduler.

Redis

Use a private Redis service with authentication. The application and LiveKit runtime may share the server but should use the configured database number. The installer default is database 2 for LiveKit coordination.

redis-cli -h 127.0.0.1 -p 6379 -a 'your-password' -n 2 ping

Queue worker

cd /var/www/playhub
php artisan queue:work --queue=videos,default --sleep=3 --tries=3 --timeout=7200

Run this through Supervisor or systemd. Do not leave it in an SSH terminal.

[program:playhub-worker]
process_name=%(program_name)s_%(process_num)02d
command=/usr/bin/php /var/www/playhub/artisan queue:work --queue=videos,default --sleep=3 --tries=3 --timeout=7200
directory=/var/www/playhub
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/playhub/storage/logs/worker.log
stopwaitsecs=7300

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start playhub-worker:*

Set the active queue connection’s retry interval above its longest job timeout. Otherwise another worker may reserve a media job while the first still runs. The documented local configuration uses timeout 21600 seconds and DB_QUEUE_RETRY_AFTER=21660; Redis needs its own corresponding override rather than the 90-second fallback. Match these values to your supervised worker and actual workload.

Laravel scheduler

Add exactly one cron entry for the web-server user. Laravel decides which internal tasks run each minute.

* * * * * cd /var/www/playhub && php artisan schedule:run >> /dev/null 2>&1

The schedule handles future video publishing, replay finalization and retention, scheduled live polls, pruning, and configured automatic backups.

FFmpeg and FFprobe

Both binaries must be executable by the queue-worker user. Set explicit paths in .env when they are not discoverable through that user's PATH.

PLAYHUB_FFMPEG_BINARY=/usr/bin/ffmpeg
PLAYHUB_FFPROBE_BINARY=/usr/bin/ffprobe
PLAYHUB_MAX_UPLOAD_MB=51200
PLAYHUB_CHUNK_SIZE_MB=8

After configuration changes

cd /var/www/playhub
php artisan optimize:clear
php artisan config:cache
php artisan queue:restart

LiveKit, RTMP, and replay recording

PlayHub uses a generated Docker runtime for WebRTC rooms, external-encoder ingress, and composite replay egress. The web installer prepares configuration, but the Docker installation must be run by a server administrator.

Install the streaming runtime

sudo /var/www/playhub/livekit/install.sh

If automatic web-user detection is incorrect, pass the PHP-FPM account:

sudo /var/www/playhub/livekit/install.sh www-data

The script creates livekit/runtime/, generates protected keys and service configuration, starts the Compose project, and registers a project-local manager through systemd when available. The generated project contains these services:

Open firewall ports

Configure the public WebSocket URL

In Admin Dashboard > System Settings > Live Streaming > LiveKit, set the public URL to a secure endpoint such as wss://video.example.com/livekit. The reverse proxy must preserve WebSocket upgrades and use a timeout appropriate for long-lived connections.

Use the guarded signaling route

Adapt the shipped livekit/nginx-app-test-location.conf to the production host, PHP upstream, document root, and actual signaling port. Verify Nginx has http_auth_request_module. The include handles the LiveKit prefix and WebSocket upgrades; avoid duplicate competing locations.

The private /__playhub_livekit_admission FastCGI subrequest calls Laravel /api/livekit/admission and validates the JWT against current stream/account/stage authorization and server-held identity versions. Cached kicked or revoked grants remain denied after token refresh. Query and Bearer credentials must agree; the exact admitted credential is passed upstream. Keep direct core signaling host-private and do not expose a bypass join route.

Suppress token-bearing signaling access/error logs: the Windows include uses NUL; Unix deployments use /dev/null. Validate before reloading. A guarded missing-token request returning 403 is expected; prove real host/viewer media and cached-token rejoin separately. See the current Live service guide for networking, health checks, queues, and TURN.

LiveKit settings reference

Start, inspect, and restart containers

docker compose -f /var/www/playhub/livekit/runtime/docker-compose.yml ps
node tools/live-health.cjs --json

docker compose -f /var/www/playhub/livekit/runtime/docker-compose.yml restart

When settings are changed from the admin dashboard, use its save/apply action so generated configuration and service status remain synchronized.

Configure RTMP for OBS

1. Enable RTMP ingress in LiveKit settings and confirm the ingress container is healthy.
2. Open Go Live and choose the external encoder workflow.
3. Copy the generated RTMP server URL and stream key. A typical URL is rtmp://video.example.com:1936/live.
4. In OBS, select Custom service, paste the server and key, and use H.264 video plus AAC audio.
5. Start OBS, then confirm the source appears in the PlayHub control room before going public.

Participants, permissions, and layouts

• The host publishes camera, microphone, and screen tracks.
• Ordinary viewers subscribe only and cannot publish.
• Accepted guests or cohosts receive role-scoped publishing permission.
• Viewers can request audio-only or audio-and-video participation when enabled.
• Moderators can manage chat, bans, requests, and participants within assigned privileges.
• Adaptive grid, host focus, split screen, and screen share update the stage and recording layout.

Recording and replay pipeline

Camera hosting requires core LiveKit and Redis; RTMP ingress and recording egress are optional services required only for their workflows. In bridge networking, configure host access through host.docker.internal/host-gateway; container loopback cannot reach a host-only Redis listener. Start the configured optional services and verify their real listeners and dependencies.

Live diagnostics

The control room diagnostics show actual connection state, source tracks, bitrate, frame rate, latency, network quality, room status, and runtime reachability. Check diagnostics before restarting services. A camera permission issue and a failed egress container require different fixes.

Configure every platform area

Most settings are available under Admin Dashboard > Website Configuration or Admin Dashboard > System Settings. Save each block independently and use its connection test where provided.

General, branding, and design

Registration, login, and account security

For OAuth, copy the exact callback URL displayed in the admin UI into the provider console. Scheme, domain, path, and trailing slash must match.

Email, SMS, analytics, and payments

• SMTP: host, port, encryption, username, password, from address, and from name.
• SendGrid: API key, sender identity, and support notification address.
• SMS OTP: Twilio, Vonage, or MessageBird credentials and a test phone number.
• Google Analytics: enable flag and Measurement ID.
• Stripe: publishable and secret keys for wallet top-ups and paid flows.
• PayPal: sandbox/live environment, client ID, and client secret.
• Payment currency: USD, EUR, GBP, CAD, or AUD in the current admin selector.
• Email templates: localized HTML/plain-text content, per-template placeholders, preview, validation, and update-safe overrides.
• Use each Test action before enabling its public feature.

Uploads and video processing

• Enable or disable public upload workflows.
• Select the allowed output renditions and default playback quality.
• Set server and PHP upload limits that match the maximum accepted file.
• Keep the videos,default worker supervised for probing, thumbnails, and encoding.
• Use moderation defaults to auto-approve, require review, set default visibility, and enable profanity filtering.
• Test with a short H.264/AAC file before accepting large production uploads.

Video import providers

Enable only providers you intend to offer. Direct URL, YouTube, Vimeo, Dailymotion, and Twitch settings support provider-specific keys or tokens where required. The mass-import tool uses the enabled provider list and can apply category, visibility, tags, kids status, monetization, duplicate handling, and stop-on-error behavior.

Live streaming product settings

Current validation supports up to 365 days for scheduling, 5 MB thumbnails, 6 poll options, 1440 poll minutes, storage of 8 stream-label settings, and a 512 KB diagnostic probe. Stored label settings do not establish a label editor or rendered overlay. Tip defaults are USD 1 minimum and USD 500 maximum unless changed.

Website ads and player ads

The website ad manager supports media or trusted HTML, placement, status, schedule, targeting, display rules, and performance data. Placements include after header, left sidebar, before footer, home feed, video grid, comments, below player, watch sidebar, Shorts, search, channel, live, community, and floating bottom.

Player ads are configured separately for VAST pre-roll, timed mid-roll, and post-roll delivery. Configure tag URLs, break timing, skip timing, wrapper depth, MP4 preference, and tracking. Test the VAST response and media CORS from a browser before enabling it globally.

Monetization

Monetization can be enabled globally with platform fees, paid-video commission, contribution limits, boost limits, purchase taxes, withdrawal review, and a creator share of completed VAST impressions. VAST revenue uses provider CPM metadata or the administrator fallback CPM with fractional earnings, self-view exclusion, hourly impression deduplication, and idempotent credits. Memberships, wallets, tips, paid videos, paid photo sets, boosts, creator earnings, and payouts depend on real transaction data and configured payment providers.

Languages

The Languages page manages the bundled 128 language packs. Select a default language, enable or disable public languages, review metadata and plural rules, edit translated PHP entries, and save. The default language cannot be disabled, and a visitor's saved preference is preserved while available. Back up customized lang/ files before applying an update.

Maintenance mode

Enable maintenance mode with a customer-facing message and optional allowed IP addresses or prefixes. Always include your administration IP before saving, then verify the public state in a private browser window.

Storage, cloud, and media lifecycle

PlayHub supports local uploads and S3-compatible cloud workflows, including Amazon S3, Google Cloud Storage interoperability, Backblaze B2, and Azure Blob configuration exposed by the admin storage page.

Storage settings

Records prefixes are normalized and applied once. Endpoint/public-base URLs require HTTP(S) without credentials, queries, or fragments. S3-compatible adapters stream reads with bounded retries/timeouts and optional checksums only when required. Default ACL omission can be disabled for a provider requiring legacy ACLs.

Saved secrets are masked. Blank secret fields preserve current values; explicit clearing is validated, partial saves preserve other settings, and replacement refreshes cached disk connections. Test Connection uses the submitted configuration to write, verify, read, and delete a unique object, checks cleanup, and sanitizes errors. It performs real provider operations and does not save the tested settings.

Set a public base URL only for intentionally public delivery. Without one, private display images use signed application links and protected video uses authorized provider redirects. See image caching and private delivery fixes. Reported cloud capacity is administrator-configured, not a queried provider quota; membership quotas are application policy. Changing provider, bucket, or prefix requires an explicit object migration.

Membership storage quotas

Starter, Plus, Premium, Pro, and VIP memberships can have independent storage quotas and monthly prices. VIP can be unlimited. A user-specific quota overrides the membership default when set by an administrator.

Video processing lifecycle

Feature guide

This section explains where each major PlayHub feature appears and what must be configured for it to operate.

Viewer experience

• Home discovery, trending blocks, categories, creators, and personalized content.
• Database-backed search for videos, channels, playlists, live streams, and tags.
• Responsive video player, quality selection, captions, progress, and watch history.
• Likes, comments, replies, mentions, reactions, attachments for signed-in users, and stickers.
• Watch Later, favorites, bookmarks, playlists, liked videos, and history collections.
• Public channel profiles, subscriptions, notifications, playlists, community, and messaging.
• Shorts feed with engagement actions and creator navigation.
• Reports for profiles, videos, comments, and community content.

Creator Studio

• Upload and edit video metadata, thumbnail, category, tags, audience, visibility, and schedule.
• Track processing status and use real channel analytics and content search.
• Moderate recent comments with reply, view, link, pin, and report actions.
• Create and manage playlists, select owned videos, and expose public collections.
• Manage channel profile, social links, description, branding, community, and library.
• Review revenue, memberships, wallet contributions, gifts, tips, and monetized events.

Community and messaging

Authenticated creators can publish community posts with text and media. Users can react, comment, report, and use categorized stickers. Suggested communities and subscription actions use real channel data. Profile Message opens the existing private conversation or creates the correct conversation destination.

Go Live and control room

• Required title and description, category, comma-separated tag tokens, visibility, schedule, and thumbnail.
• Browser camera/microphone, screen share, or external RTMP source.
• Local host preview remains muted while the published audio track stays live.
• Pre-live and in-stream settings with participant acceptance and recording controls.
• Invite guest username suggestions, backstage state, request approval, and removal.
• Adaptive grid, host focus, split screen, screen share, and spotlight behavior.
• Real diagnostics, viewer count, stream health, latency, bitrate, and track status.
• Policy-aware reconnect after recoverable network interruptions. Background and development reload behavior depend on the host lifecycle; a reload does not guarantee continued publishing.

Live engagement and commerce

• Real-time chat, reactions, pinned messages, slow mode, deletion, and viewer chat bans.
• Polls publish to every role; the host can inspect voter identities and selections.
• Goals update live when created or changed during the broadcast.
• Preset tips send immediately; custom tips enforce configured minimum and maximum.
• Gifts and categorized super stickers send immediately when wallet funds are sufficient.
• Wallet recharge opens configured Stripe or PayPal checkout in a separate tab.
• Contribution receipts drive bounded, deduplicated alerts according to stream settings.
• Chat and contribution archives show the actual recorded messages, receipts, and available system events; quick reactions are emoji chat messages.

Live roles

Replays

Completed recordings pass through replay finalization and video processing before playback is ready. Replay surfaces expose recorded media, available archived chat/events, timestamp checkpoints, likes, comments, creator information, and related replays. Checkpoints support manual seeking and are distinct from authored video chapters; archived chat is not a continuously playhead-synchronized feed. An existing Clips tab does not provide clip creation. Available counters do not establish peak/unique viewers or cumulative watch-time analytics. Multi-participant composites include participant identity tiles. See the current Live and replay capability guide for platform-specific behavior and acceptance.

Admin dashboard reference

The dashboard reads production data and applies real actions. Role and permission scopes determine which pages a team member can access.

Reports and moderation workflow

1. A signed-in user opens a report action on a supported item and submits a reason.
2. The record appears in Admin Reports with the real avatar, thumbnail, or content preview.
3. An administrator sets priority, moderator, and status or applies a bulk action.
4. Content/user actions are performed from the relevant admin page.
5. The report is resolved with an auditable status change.

Roles and notifications

Use the permission matrix to grant the smallest necessary scope. When a user is appointed as a platform or live moderator, PlayHub can send an in-app notification and configured email. Ban events can also send email; delivery requires SMTP or SendGrid.

Maintenance, backups, updates, and security

Production reliability depends on repeatable backups, service supervision, log review, and tested updates.

Backups

The admin backup dialog inventories selectable folders and their sizes, includes the database, supports large-file behavior, compression level, retention count, and automatic frequency. Large media libraries may be better protected by storage-provider versioning plus database/application backups.

• Back up the complete database.
• Back up .env, the signed license receipt, and install lock privately.
• Back up local uploads, replays, branding, gifts, stickers, and customized language files.
• Back up livekit/runtime/, especially keys, generated configuration, and certificates.
• Retain multiple generations and test restoration on a separate domain/server.

Transactional system updates

Logs and health

Keep signaling and recording-template grants out of logs and support attachments. Prefer node tools/live-health.cjs --json, categorical status/errors, and sanitized diagnostics; raw Egress logs may contain token-bearing template URLs. Redact those URLs before sharing any retained diagnostic output.

Security checklist

• Keep APP_ENV=production and APP_DEBUG=false.
• Enforce HTTPS and secure WebSockets on every public page.
• Protect .env, license files, Redis, database, LiveKit keys, and payment secrets.
• Use dedicated database and storage credentials with minimum privileges.
• Restrict Docker and server-management access to trusted administrators.
• Patch PHP, Node.js, FFmpeg, Docker, Composer packages, and the operating system.
• Review admin members, permission groups, reports, failed jobs, and logs regularly.
• Install only trusted plugins and investigate every compatibility, package-hardening, or checksum failure.
• Test backup restoration and account recovery before an incident occurs.

Troubleshooting

Start with the exact error, the service that owns the failing step, and the corresponding log. Avoid changing multiple systems at once.

Commands and important paths

Common commands

Important paths

Prepare a useful support request

Use the support channel on the CodeCanyon item page Or the Direct Support portal. A reproducible report with sanitized logs can be diagnosed much faster than a screenshot without server context.

Include

• PlayHub package version and whether this is a fresh install or update.
• Operating system, web server, PHP-FPM and CLI PHP versions.
• MySQL/MariaDB, Redis, Node.js, npm, FFmpeg, Docker, and Compose versions.
• Exact page, user role, action sequence, expected result, and actual result.
• Browser console/network error when the issue is client-side.
• Relevant Laravel, worker, web-server, PHP-FPM, or container log excerpt.
• Whether the problem reproduces with a short test video or private test stream.

License notice

PlayHub requires a valid CodeCanyon or KNL (Kontackt Direct License) purchase code during installation. Activation is tied to the installation domain and must follow the applicable Envato license. Do not redistribute the source package or share a purchase code.