How to Use GhostHub - User Guide

Quick Start

Get GhostHub running in under 5 minutes. This is all you need to start watching your media.

What you need

• GhostHub device (Raspberry Pi with GhostHub installed)
• USB drive with your photos/videos
• Phone or tablet with WiFi

What GhostHub does

Your own private media streaming service. Browse photos and videos from any device, no internet required.

Get Started in 5 Steps

1
Plug in your USB drive with photos/videos into the GhostHub device
2
Connect to WiFi: Join the "GhostHub" network
Password: ghost123
⚠️ Change this in Settings for security
3
Open browser and go to http://192.168.4.1 or http://ghosthub.local
4
Browse categories — tap any folder to start viewing
5
Swipe up/down to move between photos and videos

Basic Controls

On phone/tablet

• Swipe up = next item
• Swipe down = previous item
• Swipe right = back to categories
• Tap = play/pause videos

On computer

• Arrow down = next item
• Arrow up = previous item
• Click back arrow = return to categories
• Click = play/pause videos

Who This Is For

Perfect for

• Families sharing photos/videos at home or remotely
• Privacy-conscious users who want local-first media
• Remote streaming via secure tunnels (no port forwarding)
• Small gatherings and watch parties
• Anyone who wants "plug and play" media

Not for

• Users expecting fully-managed, always-on cloud hosting
• Large organizations needing multi-user accounts
• People who want to edit/delete files from the UI
• Users requiring automatic transcoding
• Those who need granular user permissions

Everyday Features

These are the features you'll use most often for watching and sharing media.

Browsing Your Media

GhostHub shows your USB folders as "categories" on the home screen.

Category cards show:

• Thumbnail preview of folder contents
• Media count (e.g., "42" items)
• Type icon: 🎬 for videos, 🖼️ for photos
• Progress bar if you're watching through a folder

Navigation tips

Filter by All, Videos, or Photos at the top
Use arrows ⬆️⬇️ to see if more items exist
Double-tap for fullscreen on videos

Continue Watching

GhostHub remembers where you left off, like Netflix.

What you'll see:

• Category badges show your position: "15/42"
• Red progress bars on category cards
• "Continue Watching" row in Streaming layout

Note: This needs to be enabled by the admin in Settings.

Sync Mode

Watch together with friends and family. Everyone sees the same thing at the same time.

How it works:

First person to click "Sync" becomes the Host
Host controls what everyone sees
Guests automatically follow along
Guests can't change items — just watch

Perfect for watch parties or showing photos to a group.

Casting to TV

Send media to your TV if your GhostHub is connected via HDMI (admin only).

To cast:

Make sure TV is connected to GhostHub via HDMI
Claim admin (click the lock icon)
Browse to any media item
Click the cast button 📺 in the header

Control playback from your phone — TV follows along.

Layouts & Themes

Choose how you want to browse and how GhostHub looks.

Default Layout

Grid of folders. Classic, simple view.

Streaming Layout

Netflix-style horizontal browsing with rows.

Gallery Layout

Google Photos-style timeline by date.

Built-in themes: Dark, Midnight, Nord, Monokai, Dracula.

Theme Builder (Custom Themes)

Create your own color themes:

Open Settings → Themes & Layout → "Open Theme Builder"
Choose a preset palette or customize individual colors (Primary, Secondary, Accent, Background, Surface, Text)
Use Random for new palettes, or Invert to flip light/dark
Preview in real-time, then click Save Theme

Custom themes appear in the dropdown with ✨

Advanced / Admin

Power-user features, file management, and administrative controls.

File Management

Upload and download files to your USB drives (admin for uploads, anyone can download).

Upload methods:

• Admin File Manager: Settings → File Manager (full control)
• Gallery drag-and-drop: Desktop only, password protected
• Chunked uploads: Large files upload in pieces for reliability

Supported formats: JPG, PNG, MP4, WebM, plus others. Up to 16GB per file.

Remote Access (Tunnels)

Access GhostHub from anywhere using secure tunnels (admin only).

Requirements:

• GhostHub connected to home WiFi (not just AP mode)
• Internet connection for tunnel setup

Providers:

• Cloudflare Tunnel: Free, pre-installed
• Pinggy: Easy setup, requires token

Click the tunnel button (🔗) in the header to configure.

WiFi Settings (Pi Only)

Configure the GhostHub WiFi network when running in Access Point mode.

What you can change:

• Network Name (SSID): The name that appears when connecting (1-32 chars)
• Password: WiFi password (8-63 characters)
• Channel: WiFi channel 1-11 (default: 7)
• Country Code: Two-letter code for regulatory compliance

Access via Settings → WiFi Settings. Changes require a brief WiFi restart — devices will need to reconnect.

Chat Commands

Type commands in chat for quick actions.

Everyone can use:

• /help — show all commands
• /myview — share what you're viewing
• /search query — find files
• /add — add to session playlist
• /play 10 — auto-play (10s per image)

Admin only:

• /kick user_id — remove user
• Access Settings and File Manager
• Cast to TV
• Configure tunnels

Admin Features

First person to click the lock icon (🔒) becomes admin for the session.

Admin can:

• Access Settings (themes, passwords, features)
• Use File Manager for uploads/downloads
• Cast media to TV
• Set up remote tunnels
• Kick users with /kick
• Clear saved data and update GhostHub

Click the lock again to release admin role for others.

USB Hotplug

GhostHub automatically detects when you plug in or remove USB drives.

What happens:

• Plug in: Drive is scanned, new categories appear
• Remove: Categories become unavailable, progress is saved
• Thumbnails: Generated in background (you'll see progress)

Drives mount to /media/pi/DRIVENAME automatically.

Reference

Quick reference for indicators, troubleshooting, and settings.

UI Indicators

Indicator	Meaning
🎬	Contains videos
🖼️	Images only
🔄	Generating thumbnails
Red progress bar	Video playback progress
⬆️/⬇️	Previous/next items available
Green ▶	Auto-play active
📺 (red)	Currently casting to TV
"Sync Mode: HOST"	You're controlling sync
🔒 (filled)	You are admin

Quick Troubleshooting

Common issues

• Media not showing: Check USB connection, refresh page
• Videos won't play: Try different browser, check format (MP4 works best)
• Sync not working: Check connection, refresh both devices
• Cast button missing: Must be admin, TV must be connected via HDMI

Performance tips

• Use USB drives instead of SD card for media
• Large folders take time to index initially
• Refresh page if things seem stuck
• Very large files may buffer on slow networks

Key Settings (Admin)

Important settings

• Session Password: Protect access with password
• Save Current Index: Enable Continue Watching
• Enable Session Progress: Let guests save their own progress
• Enable Subtitles: Show subtitle tracks if available

Layout & themes

• UI Layout: Default/Streaming/Gallery
• Color Theme: 5 built-in + custom themes
• Theme Builder: Create custom color themes
• Feature toggles: Show/hide chat, indicators

WiFi Settings (Pi only)

• Network Name/Password: Customize AP credentials
• Channel/Country: WiFi channel and regulatory code

Final Tips

• Try different layouts: Streaming for movies, Gallery for photos
• USB is your friend: Keep media on USB drives for best performance
• Share with /myview: Easy way to show someone a specific item
• Build playlists: Use /add for watch parties
• Refresh if stuck: Most issues solved by refreshing the page

Happy browsing! 👻

👻 How to Use GhostHub

Quick Navigation