Your own TikTok for the videos and photos you already have.
Self-hosted. No cloud account. Your library stays with you.

Spooly turns a folder of media into a private feed. Run one command on your computer or NAS, open it on your phone, and swipe through your own videos and photos full screen — or browse them as a Pinterest-style grid and a year/month timeline. Browsing and playback stay on your server; optional AI features send selected images to the provider you configure.

Local browsing and playback work without internet access. URL downloads and remote AI features require a connection.

Quick start

Requires Python 3.10+.

pip install spooly
spooly ~/Videos

Open http://<your-computer>:8000 on any phone, tablet, or browser on the same network. The first start prints an access password in the terminal.

What it does

• Flow — a full-screen vertical feed that mixes videos and images. Swipe to the next item, double-tap to favorite, hold a video to play it at 2×, and drag sideways to seek.
• Library — a year/month timeline for multi-year archives and an Explore grid with random images, latest videos, and large files.
• Home — pick up where you left off, see what happened On This Day, and open your collections.
• Favorites and collections — save anything from any view; long videos resume where you stopped, across devices.
• Downloads — paste a link and Spooly fetches it into your library with yt-dlp or gallery-dl.
• Radio — an ambient audio player for the music in the same folders.
• Many folders, one library — merge several media directories; deletions go to a trash you can undo.

_{Screenshots use CC0 and public-domain photos and clips from Wikimedia Commons.}

Flow controls

Files the browser cannot play (for example some HEVC or AV1 videos) are skipped with a short note instead of stopping the feed.

Configuration

Settings come from command-line options, then environment variables (MEDIA_ROOT, SPOOLY_HOST, SPOOLY_PORT), then ~/.config/spooly/config.yaml:

media_sources:
  - id: default
    name: Main Library
    path: ~/Videos/Spooly
  - id: photos
    name: Photos
    path: ~/Pictures
download_source: default   # where URL downloads are saved
name: Studio Mac           # shown in the browser tab
port: 8000

A single media_root: ~/Videos still works. Sources are merged into one library; media URIs look like @source_id/path, and old bare-path links and favorites keep working through the default source.

spooly /path/to/media                        # start with one folder
spooly --port 9000                           # custom port
spooly --media-source photos=~/Pictures/AI   # add a source (repeatable)
spooly --help

Access password

Sign-in is on by default. Every page, API and media file requires it.

spooly auth status          # status and storage path
spooly auth set-password    # new password; signs out existing sessions
SPOOLY_AUTH_PASSWORD='a-long-private-password' spooly auth set-password

The password is stored as a scrypt hash in ~/.spooly/auth.json. Keep Spooly on a trusted network.

HTTPS

Spooly serves plain HTTP. For HTTPS, put it behind a reverse proxy that keeps the original Host header and media Range requests, and mark the session cookie secure:

FLASK_AUTH_COOKIE_SECURE=true spooly ~/Videos --host 127.0.0.1 --port 8000

URL downloads

The /download page queues background downloads. Install the tools it uses:

brew install yt-dlp gallery-dl ffmpeg        # macOS
sudo apt install yt-dlp gallery-dl ffmpeg    # Ubuntu / Debian

• yt-dlp (required) handles video sites; Spooly asks it for H.264/AAC so downloads play in every browser. gallery-dl handles image posts and albums. ffmpeg merges formats and makes video thumbnails.
• For sign-in-only content, put cookie files saved from your browser in ~/.spooly/cookies with the domain in the name (x.com.txt, youtube.com.cookies), or upload them on the download page.

Stopping the server (Ctrl + C or SIGTERM) cancels unfinished downloads and keeps finished files; interrupted jobs are not resumed.

spooly thumbs /path/to/media              # generate video thumbnails
spooly thumbs /path --overwrite           # regenerate

spooly dedupe /path/to/media              # dry run
spooly dedupe /path --type video          # videos only
spooly dedupe /path --keep newest --execute

vision:
  enabled: true
  base_url: https://openrouter.ai/api/v1
  model_name: google/gemini-2.5-flash
  tags_limit: 5

experiments:
  similarity:
    enabled: true

embedding:
  enabled: true
  base_url: https://openrouter.ai/api/v1
  model_name: google/gemini-embedding-2
  dimensions: 768
  image_max_size: 512
  image_quality: 82

spooly vectorize ~/Videos --dry-run                  # see what would be sent
spooly vectorize ~/Videos --limit 200 --order latest
spooly vectorize ~/Videos --source photos --cleanup
spooly analyze-similar ~/Videos --limit 500 --yes

Documentation

• Docs index
• Flow interaction
• Media index and local recommendation
• Release notes

Contributing

Bug reports, ideas and pull requests are welcome on GitHub. To refresh the screenshots, serve a demo folder without sign-in and run the capture script (it uses your installed Chrome, or the executable set by CHROME_PATH):

npm install
SPOOLY_INSTANCE=/tmp/spooly-demo FLASK_AUTH_ENABLED=false spooly demo-media --host 127.0.0.1 --port 8793
node scripts/screenshots.mjs

Made by Oddloaf. Contact hello@oddloaf.dev, or open an issue.

License

MIT