simpleparty 0.3.1

Easily enjoy your private video collection

SimpleParty

Easily enjoy your private video collection. Browse and play local video files from any device on your network. Zero dependencies.

Features

• Directory browsing - navigate nested folders with breadcrumb navigation
• Shuffle play - randomize playback within any directory
• Delete - remove videos you don't want, right from the player
• Keyboard shortcuts - full control without touching the mouse
• Dark theme - comfortable for extended viewing
• Mobile friendly - responsive layout with large tap targets
• Auto-transcoding - MKV/AVI/MOV files are automatically transcoded via ffmpeg or VLC (if installed)
• AI video tagging - automatically tag videos using a local Ollama vision model (opt-in, requires --tag flag)
• Manual tagging - add or edit tags on any video from the player page
• Tag summary - see all tags in a directory at a glance, with counts
• Encrypted directories - unlock/lock fscrypt-encrypted folders from the browser (if fscrypt is installed)
• Zero dependencies - pure Python standard library, nothing to install

Install

# With uv (recommended)
uv pip install simpleparty

# Or run directly without installing
uvx simpleparty /path/to/videos

Usage

simpleparty /path/to/videos

With no arguments, serves the current directory:

cd ~/Videos && simpleparty

Then open http://localhost:1312 in your browser (or use your machine's hostname/IP from another device).

Options

simpleparty [/path/to/videos] [options]

  -p, --port PORT       Port to listen on (default: 1312)
  -b, --bind ADDR       Bind address (default: 0.0.0.0)
  --no-delete           Disable the delete button
  --no-transcode        Disable ffmpeg/VLC transcoding
  --no-tag              Disable all tagging features
  --tag-model MODEL     Ollama vision model (default: huihui_ai/qwen3-vl-abliterated:8b)
  --ollama-url URL      Ollama API URL (default: http://localhost:11434)

Keyboard shortcuts

Key	Action
n / Right	Next video
p / Left	Previous video
s	Toggle shuffle
d	Delete current video
f	Toggle fullscreen
Space	Play / pause
m	Mute / unmute
Esc	Go to parent directory
?	Show shortcut help

Optional features

These are auto-detected at startup and require no configuration:

• ffmpeg or VLC - Enables playback of MKV, AVI, and MOV files by transcoding to browser-compatible MP4 on the fly. Install either one: sudo apt install ffmpeg / sudo pacman -S ffmpeg
• fscrypt - If your video directories use Linux filesystem encryption (fscrypt), SimpleParty will detect locked directories and prompt for the passphrase in the browser

AI tagging

Tagging is always available — you can manually add or edit tags from the video player page, no setup required. Tags are stored in a .simpleparty-tags.json file per directory.

For AI-powered automatic tagging, SimpleParty uses a local vision language model via Ollama. This runs entirely on your machine — no data leaves your network. If Ollama and ffmpeg are available, a "Tag" button appears in the directory browser. Click it to tag all untagged videos in that directory. Tagging runs in the background — you can close the browser and it will keep going as long as the server is running.

AI tagging setup

1. Install Ollama
2. Pull a vision model: ollama pull huihui_ai/qwen3-vl-abliterated:8b
3. Start SimpleParty — AI tagging is auto-detected:

simpleparty /path/to/videos

AI tagging requirements

• Ollama running locally (or specify --ollama-url)
• ffmpeg for extracting video keyframes
• A GPU with ~8GB VRAM for the default 8B model (NVIDIA recommended)

If these aren't available, SimpleParty still works — you just won't see the AI "Tag" button. Manual tagging always works.

Why not Jellyfin/Plex?

Those are full media centers with databases, metadata scraping, user accounts, and transcoding pipelines. SimpleParty is for when you just want to open a folder of videos and watch them. One command, no setup, no database.

License

AGPL-3.0