👻 How to Use GhostHub
A friendly guide for regular users who have a GhostHub Pi device set up and ready to go.
Overview
GhostHub is your personal media hub that lets you browse photos and videos stored on a USB drive, all from your phone or computer's web browser. Think of it like having your own private TikTok feed, but with your own content.
What GhostHub does:
- ✓Displays your photos and videos in a swipeable, mobile-friendly feed
- ✓Remembers where you left off (Continue Watching)
- ✓Lets multiple people watch together in sync (Sync Mode)
- ✓Casts media to a TV display (Admin only)
- ✓Works entirely offline — no internet required
What you need:
- •A GhostHub device (Raspberry Pi)
- •A USB drive with your media files plugged into the device
- •Any phone, tablet, or computer with a web browser
Getting Started
- 1Connect to GhostHub: Open your web browser and go to your GhostHub's address (usually something like
http://ghosthub.local:5000orhttp://192.168.x.x:5000). - 2Browse categories: You'll see a grid of "categories" — each category is a folder from your USB drive. Tap or click one to start viewing.
- 3Navigate media: Swipe up/down on mobile or use arrow keys on desktop to move through items.
Admin Role
GhostHub has a single Admin role that controls special features. There are no user accounts — just one admin at a time.
How to become Admin
Look for the lock button in the header. If no one is currently admin, click it to claim admin. It's first-come, first-served — whoever clicks it first becomes admin.
Lock button states:
- Open lock icon — No admin yet, click to claim
- Shield with checkmark — You ARE the admin (click to release)
- Locked icon (disabled) — Someone else is admin
What the Admin can do:
- Access SettingsConfigure every GhostHub option
- Start Sync ModeTake over and control what everyone sees
- Cast to TVTrigger the TV display feature instantly
- Manage categoriesAdd, rename, or reorder folders manually
- Kick & block usersRemove troublemakers and block IPs temporarily
- Set session passwordRestrict access to trusted people only
- Start tunnelsEnable remote access via Cloudflare or Pinggy
Releasing Admin
Click the shield button (while you're admin) to release your admin status. The icon changes back to an open lock and anyone can claim it.
Note: If you're not the admin, you can still browse and view all media. You just won't see admin-only buttons like Settings, Cast, or user management.
Browsing & Navigation
Category View (Home Screen)
When you first open GhostHub, you see your media organized into categories — these are folders from your USB drive.
What you'll see on each category card:
- Thumbnail: A preview image of the folder's contents
- Media count badge: Shows total items (e.g., "42") or your position if Continue Watching is on (e.g., "15/42")
- Type icon: 🎬 for video folders, 🖼️ for image-only folders
- Progress bar: A small red bar at the bottom showing how far into a video you were (if Continue Watching is enabled)
- Activity indicator: Shows if others are currently viewing this category
Filtering categories: If there are many categories, you can page through them using the pagination controls at the bottom.
Inside a Category (Media View)
Once you tap a category, you enter the full-screen media viewer.
📱 On mobile (touch screens):
- Swipe up: Next item
- Swipe down: Previous item
- Swipe right: Go back to categories
- Tap: Play/pause videos
- Double-tap: Enter fullscreen mode for videos
💻 On desktop (keyboard/mouse):
- Arrow Down / Scroll Down: Next item
- Arrow Up / Scroll Up: Previous item
- Click the back arrow (top-left): Return to categories
- Escape: Close modals/popups
What the arrows mean: ⬆️ appears when there are previous items • ⬇️ appears when there are more items to see
Videos vs Images
- Videos: Tap the thumbnail to start playing. Videos loop by default. Tap to pause, tap again to play.
- Images: Display instantly. Just swipe to move on.
Going Fullscreen
For videos, you can:
- Double-tap on mobile to go fullscreen
- Click the fullscreen button (expand icon) that appears on videos
Continue Watching
GhostHub can remember where you left off in each category, so you can pick up right where you stopped — like Netflix.
How it works
When Save Current Index is enabled (by the admin):
- The app remembers which item you were on in each category
- For videos, it also remembers your exact playback position
- When you return to a category, you'll automatically jump to where you left off
- Shuffle is automatically disabled to ensure consistent ordering
What you'll see
- Category badges show your position: "15/42" means you're on item 15 of 42
- Progress bars on category cards show how far into the current video you were
- Thumbnails update to show the last item you viewed
Two tracking modes
The admin can set progress tracking to work in one of two ways:
Per-Category mode (default)
Your position in each category is saved. Good for watching through folders sequentially.
Per-Video mode
Progress is saved for each video individually. Good if you're jumping around and want to resume specific videos.
Admin vs Guest Progress Storage
Admin Progress
Saved to SQLite database on the Pi:
- • Persists across all devices
- • Survives browser restarts
- • One "master" progress track
Guest Progress
By default: NOT saved
With "Enable Session Progress" ON:
- • Saved to browser localStorage
- • Each device has its own progress
- • Cleared if browser data cleared
- • Doesn't affect admin's progress
Why this matters: Multiple family members can each have their own place without overwriting each other — as long as Session Progress is enabled. The admin's progress is the "master" saved on the Pi.
Subtitles
If the admin has enabled subtitles and your video files have subtitle tracks (embedded in MP4s or as separate .srt/.vtt files), they'll appear automatically.
Supported formats:
- • Embedded subtitles in video files
- • External
.srtfiles (same name as the video) - • External
.vttfiles (same name as the video)
Subtitles use your browser's built-in subtitle controls — look for the CC button in the video player.
Sync Mode
Sync Mode lets everyone see the same thing at the same time — great for watching together remotely or controlling a viewing party.
How Sync Mode works
- One person becomes the Host: The first person to enable Sync Mode controls what everyone sees.
- Others join as Guests: Guests automatically follow along with whatever the Host is viewing.
- Navigation is locked for Guests: Guests can't swipe to change items — they just watch.
Starting Sync Mode (becoming Host)
- Navigate to the media you want to share
- Click the "Sync" button (in the header)
- You're now the Host — everyone connected will see "Sync Mode: ON"
Joining as a Guest
If someone else already started Sync Mode:
- • You'll automatically join as a guest
- • The header will show "Sync Mode: ON"
- • You'll be taken to whatever the Host is viewing
- • Your swipe controls are disabled — just watch and enjoy
Stopping Sync Mode
- Host clicks "Stop Sync" — ends sync mode for everyone
- Anyone can disable sync — clicking the sync toggle when active will end the session for everyone
Note: A guest disconnecting or closing their browser does NOT end sync mode. Only explicitly toggling sync off will end it.
✓ What Guests CAN do
- • Watch the synced media
- • Use the chat to communicate
- • Go fullscreen on videos
- • Adjust their own volume
✗ What Guests CANNOT do
- • Swipe to change items (navigation locked)
- • Use keyboard arrows to navigate
- • Control playback for everyone (Host controls play/pause/seek)
Important: When Sync Mode is on, media shuffle is automatically disabled. This ensures everyone sees items in the same order.
Casting to TV
GhostHub can send media directly to a TV connected to the Pi — like Chromecast, but completely local.
How it works
- Connect HDMI from your Raspberry Pi to your TV
- GhostHub automatically detects the connection and starts Kiosk Mode
- The TV shows a waiting screen (the display page loads automatically)
- On your phone/computer, claim admin if you haven't already
- Browse to any media and click the 📺 Cast button in the header
- The media appears on your TV!
Requirements
- HDMI cable from Pi to TV
- You must be the Admin to cast
- GhostHub installation must include kiosk setup (default)
Controlling TV playback
Once casting:
- Play/pause on your device — TV follows
- Seek in videos — TV syncs position
- Cast button turns red when actively casting
- Click the cast button again to stop casting
Automatic HDMI detection: When you plug in/unplug HDMI, the kiosk automatically starts/stops. No need to manually configure anything — just plug in and go!
Who can cast? Only the Admin can cast and control the TV. Non-admins won't see the cast button.
USB Hotplug (Automatic Detection)
GhostHub automatically detects when you plug in or unplug USB drives.
When you plug in a USB
- GhostHub scans the drive for media folders
- New categories appear automatically
- Thumbnails are generated in the background (you'll see a loading indicator)
When you remove a USB
- • Categories from that drive become unavailable
- • Your progress for those categories is kept (it'll be there when you plug it back in)
Where to plug in USB drives
GhostHub looks for media in common locations:
/media (most USB drives mount here on Raspberry Pi) •/media/pi •/media/usb •/mntThumbnail generation
When GhostHub finds new media, it creates preview thumbnails. For large folders:
- You'll see a spinning indicator on the category card
- A progress bar shows how far along thumbnail generation is
- You can still browse the category while thumbnails are being created
Chat & Commands
GhostHub includes a simple real-time chat. Open it by clicking the chat icon (💬).
Slash Commands
Type these in the chat to perform actions:
| Command | What it does |
|---|---|
| /help | Shows all available commands |
| /myview | Shares your current view as a clickable link others can click to jump to |
| /view <user_id> | Jump to what another user is viewing (use their 8-char ID from chat) |
| /search <query> | Search for files by name across all categories |
| /find <query> | Same as /search |
| /play [seconds] | Start auto-play mode (images show for X seconds, videos play fully) |
| /play stop | Stop auto-play |
| /random | Jump to a random item in the current category |
| /add | Add current item to the shared Session Playlist |
| /remove | Remove current item from the Session Playlist |
| /kick <user_id> | (Admin only) Kicks a user and blocks their IP for the session |
Session Playlist
The Session Playlist is a shared virtual category that anyone can add items to using /add.
- Shows up as a special category called "Shared Session Playlist"
- Clears when the server restarts
- Great for building a shared watch queue with friends
Auto-Play Mode
Use /play to automatically advance through media:
- Images display for the specified time (default: 10 seconds)
- Videos play to the end, then advance
- A green ▶ indicator appears in the corner when active
- Use
/play stopto turn it off
Performance Notes (Raspberry Pi)
GhostHub is optimized to run smoothly on Raspberry Pi:
What helps performance
- USB drives: Store your media on USB, not the SD card — much faster
- Lazy loading: Thumbnails load as you scroll, not all at once
- Background processing: Thumbnail generation happens without blocking you
Large folders
If a category has thousands of files:
- Initial loading takes longer
- You'll see an "Indexing" progress indicator
- Once indexed, browsing is fast
- The index is cached, so it's fast next time
Memory management
GhostHub automatically cleans up memory:
- Old media elements are removed as you scroll away
- Video resources are released when not visible
- The app uses conservative caching on mobile devices
Limitations
What GhostHub doesn't do
- No user accounts: There's no login system. Admin is claimed first-come, first-served.
- No editing: You can't edit, delete, or organize files from the app.
- No transcoding: Videos play in their original format. If your browser can't play a format, it won't work.
- No offline caching: Media streams from the device; nothing is saved to your phone.
Browser compatibility
GhostHub works best in modern browsers:
- Chrome/Edge (recommended)
- Safari (iOS)
- Firefox
Video format support
Depends on your browser.
✓ Generally supported
- • MP4 (H.264)
- • WebM
⚠ May have issues
- • MKV (some browsers)
- • AVI (most browsers)
- • MOV (varies)
Large files
Very large video files (several GB) may be slow to start or buffer. This depends on your network speed to the GhostHub device.
Quick Fixes / Troubleshooting
Media isn't showing up
- • Check the USB: Make sure it's plugged in properly
- • Refresh the page: Pull down on mobile or press F5 on desktop
- • Give it time: Large folders take time to index
Videos won't play
- • Try a different browser: Some video formats only work in certain browsers
- • Check the format: MKV and AVI may not play; try MP4 or WebM
Thumbnails are missing
- • Wait for generation: Thumbnails are created in the background
- • Check the progress indicator: A spinning icon means it's working
Sync Mode isn't working
- • Check your connection: Both devices need to reach the GhostHub server
- • Someone might already be Host: Only one person can be Host at a time
- • Try refreshing: Sometimes the connection drops — refresh both devices
Progress isn't being saved
- • Check if it's enabled: The admin needs to turn on "Save Current Index" in settings
- • Are you the admin? Non-admin progress is saved locally in your browser (if session progress is enabled)
- • Try refreshing: Progress saves periodically; make sure you've given it time
Cast button doesn't appear
- • Are you admin? Only the admin can cast
- • Is HDMI plugged in? The Pi needs to detect a connected TV
- • Wait for kiosk: Give it a few seconds for the TV display to connect
Everything is slow
- • Using SD card for media? Move your files to a USB drive
- • Too many large files? GhostHub works better with reasonable file sizes
- • Network issues? Check your WiFi signal to the Pi
"Password Required" prompt
If the admin set a session password, you'll need to enter it to view categories, use Sync Mode, and use most commands. Ask whoever set up GhostHub for the password.
UI Indicators Reference
| Indicator | Meaning |
|---|---|
| 🎬 | Category contains videos |
| 🖼️ | Images only |
| 📁 | No thumbnail yet (placeholder) |
| 🔄 | Generating thumbnails |
| 👤 | 1 person viewing this category |
| 👥 2 | Multiple people viewing (number shown) |
| Red progress bar | Video playback progress |
| "15/42" badge | Your position (Admin: SQLite, Guests: localStorage if enabled) |
| ⬆️ | Previous items available |
| ⬇️ | More items available |
| Green ▶ (top-right) | Auto-play is active |
| 📺 button (red) | Currently casting to TV |
| "Sync Mode: HOST" | You're controlling the sync session |
| "Sync Mode: ON" | You're following someone else |
Settings (Admin Only)
The admin can configure GhostHub by clicking the ⚙️ gear icon. Settings are saved to instance/ghosthub_config.json.
Progress & Playback Settings
| Setting | What it does |
|---|---|
| Save Current Index | Enables Continue Watching — admin progress saves to SQLite database. Auto-disables shuffle. |
| Progress Tracking Mode | Per-Category: saves position in folder. Per-Video: saves timestamp for each video file. |
| Enable Session Progress | Lets non-admins save progress to their browser's localStorage (doesn't affect admin's server-side progress) |
| Shuffle Media | Randomizes media order. Auto-disabled when Save Current Index or Sync Mode is on. |
| Enable Subtitles | Detects embedded MP4 subtitles and external .srt/.vtt files. Requires ffmpeg. |
Security Settings
| Setting | What it does |
|---|---|
| Session Password | Password-protects access. Users are prompted when: opening categories, enabling Sync Mode, or using chat commands. Validation is cached briefly to avoid repeated prompts. |
Remote Access (Tunneling)
GhostHub can create a secure tunnel to access your Pi from anywhere on the internet:
Cloudflare Tunnel
Free, requires cloudflared installed. Creates a random URL.
Pinggy
Free tier available. Can use access token for persistent URL.
Start/stop tunnels from Settings → Tunnel section. The public URL will be displayed and can be shared.
💡 Final Tips
- 📱Use your phone: GhostHub is designed for mobile-first swiping
- 💾USB is your friend: Keep media on USB drives for best performance
- 🔗Share with /myview: The easiest way to show someone a specific item
- 🎬Don't fight Sync Mode: If you're a guest, just enjoy the ride
- 🔄Refresh if stuck: Most issues are solved by a simple page refresh
Happy browsing! 👻