swiparr

Swiparr

Discover what to watch next, by yourself or together.

Swiparr turns the dreaded "what should we watch?" question into a fun, collaborative experience.

Like Tinder for movies, but smarter and works for groups.

---

The Problem

The struggle is real: 30 minutes of "what should we watch?" that ends with watching the same show again. Swiparr fixes this by:

✨ Turning discovery into a fun, game-like experience
Finding content everyone actually wants to watch
⚡ Making group decisions in minutes, not hours
Working with your existing media libraries OR standalone

---

✨ Features

Content Discovery

• Intuitive Swipe Interface - Browse movies with a familiar card-based design
• Multi-Provider Support - Works with Jellyfin, Emby, Plex, or TMDB directly
• Smart Matching - Automatically finds content everyone in your group will enjoy
• Mobile-First - Optimized for phones, with desktop keyboard shortcuts
• PWA Ready - Install as a web app for the best experience

Built for Groups

• Instant Sessions - Create or join in seconds, no complex setup
• Flexible Match Rules - Choose "any two people" or "everyone must agree"
• Session Controls - Limit likes, dislikes, or total matches
• Watchlist Sync - Seamlessly save favorites back to your media server

Universal Compatibility

• Jellyfin - Full native integration
• Emby - Experimental support (improving)
• Plex - Experimental support (improving)
• TMDB - No media server required, works standalone

---

Quick Start

Fastest: Swiparr Global

No setup, no server, no problem.

swiparr.com - Free to use, community-supported (hopefully)

Easiest: Deploy to Vercel

One-click deployment, perfect for personal or small group use: %2C%20or%20set%20another%20PROVIDER%20(jellyfin%2C%20plex%2C%20emby)%2C%20or%20set%20PROVIDER_LOCK%20to%20%22false%22%20to%20configure%20the%20provider%20(any)%20at%20run-time.&envLink=https%3A%2F%2Fgithub.com%2Fm3sserstudi0s%2Fswiparr%3Ftab%3Dreadme-ov-file%23environment-variable-matrix&project-name=swiparr&repository-name=swiparr&demo-title=Swiparr&demo-description=Discover%20what%20to%20watch%20next%2C%20by%20yourself%20or%20together.&demo-url=https%3A%2F%2Fswiparr.com&demo-image=https%3A%2F%2Fswiparr.com%2Ficon1.png&products=%5B%7B%22type%22%3A%22integration%22%2C%22integrationSlug%22%3A%22tursocloud%22%2C%22productSlug%22%3A%22database%22%2C%22protocol%22%3A%22storage%22%2C%22group%22%3A%22%22%7D%5D)

Note: The automatic deployment workflow in Vercel uses the Turso integration by default as a database service provider. Free to set up, possible to swap out [^1].

Vercel security note: AUTH_SECRET is auto-generated during the build (via scripts/ensure-auth-secret.cjs) and persisted in the database when not provided.

Full Control: Self-Host with Docker

Using Docker Compose (Recommended):

1. Create docker-compose.yml:

services:
  swiparr:
    image: ghcr.io/m3sserstudi0s/swiparr:latest
    container_name: swiparr
    restart: unless-stopped
    environment:
      - PROVIDER=jellyfin  # or plex, emby, tmdb (or set PROVIDER_LOCK to "false")
      - JELLYFIN_URL=http://your-jellyfin:8096 # adjust to provider, none without server lock
    volumes:
      - ./swiparr-data:/app/data
    ports:
      - 4321:4321

1. Run it:

docker compose up -d

Using Docker CLI:

docker run -d \
  --name swiparr \
  --restart unless-stopped \
  -p 4321:4321 \
  -v $(pwd)/swiparr-data:/app/data \
  -e PROVIDER=jellyfin \
  -e JELLYFIN_URL=http://your-jellyfin:8096 \
  ghcr.io/m3sserstudi0s/swiparr:latest

1. Open http://localhost:4321

Docker security note: AUTH_SECRET is auto-generated on first boot (via scripts/ensure-auth-secret.cjs) and stored in the database when not provided.

---

⚙️ Configuration Reference

Provider-Specific Settings

Choose one provider setup based on your needs:

Jellyfin Setup

PROVIDER=jellyfin
JELLYFIN_URL=http://your-jellyfin:8096              # Internal URL (required)
JELLYFIN_PUBLIC_URL=https://jellyfin.example.com    # Public URL (optional)
JELLYFIN_USE_WATCHLIST=false                         # Use Watchlist (plugin needed) vs Favorites (optional)

Emby Setup (Experimental)

PROVIDER=emby
EMBY_URL=http://your-emby:8096        # Internal URL (required)
EMBY_PUBLIC_URL=https://emby.example.com  # Public URL (optional)

Plex Setup (Experimental)

PROVIDER=plex
PLEX_URL=http://your-plex:32400       # Internal URL (required)
PLEX_PUBLIC_URL=https://plex.example.com # Public URL (optional)

TMDB Setup (No Server Required)

PROVIDER=tmdb
TMDB_ACCESS_TOKEN=your-tmdb-token     # API Read-Only Token (required)
TMDB_DEFAULT_REGION=SE                # Default region for availability/certifications (optional)

Security & Advanced Options

…

Environment Variable Matrix

Variable	Required?	Default	Description
PROVIDER	✳️	jellyfin	Primary media provider (jellyfin, tmdb, plex, emby)
PROVIDER_LOCK	❌	true	If true, users cannot change the provider at runtime
JELLYFIN_URL	✳️	-	Internal URL of your Jellyfin server
JELLYFIN_PUBLIC_URL	❌	-	Public URL of your Jellyfin server (for client-side access)
JELLYFIN_USE_WATCHLIST	❌	false	Use Jellyfin Watchlist instead of Favorites
EMBY_URL	✳️	-	Internal URL of your Emby server
EMBY_PUBLIC_URL	❌	-	Public URL of your Emby server (for client-side access)
PLEX_URL	✳️	-	Internal URL of your Plex server
PLEX_PUBLIC_URL	❌	-	Public URL of your Plex server (for client-side access)
PLEX_TOKEN	❌	-	Plex Admin/Access Token
TMDB_ACCESS_TOKEN	✳️	-	TMDB API Read-Only Access Token
TMDB_DEFAULT_REGION	❌	SE	Default TMDB region (ISO 3166-1) for streaming availability/certifications
AUTH_SECRET	❌	Auto-generated on boot/build	Secret used for session encryption and guest lending token encryption (min 32 chars). See Security & Privacy.
USE_SECURE_COOKIES	❌	false	Set to true for HTTPS deployments
DATABASE_URL	❌	file:/app/data/swiparr.db	SQLite path or Turso URL [^1]
DATABASE_AUTH_TOKEN	❌	-	Auth token for remote databases (e.g. Turso)
APP_PUBLIC_URL	❌	swiparr.com	The public domain where the app is hosted
URL_BASE_PATH	❌	-	Base path for subpath deployments (e.g. /swipe). Must be set at image build time — see Custom Base Path.
ADMIN_USERNAME	❌	-	Global admin username (overrides provider-specific) [^2]
JELLYFIN_ADMIN_USERNAME	❌	-	Jellyfin-specific admin username [^2]
EMBY_ADMIN_USERNAME	❌	-	Emby-specific admin username [^2]
PLEX_ADMIN_USERNAME	❌	-	Plex-specific admin username [^2]
X_FRAME_OPTIONS	❌	DENY	Security header: X-Frame-Options
CSP_FRAME_ANCESTORS	❌	none	Security header: Content-Security-Policy frame-ancestors
ALLOW_PRIVATE_PROVIDER_URLS	❌	false	Allow private/LAN provider URLs for BYOP user inputs
PLEX_IMAGE_ALLOWED_HOSTS	❌	-	Extra allowlist for Plex image hosts (comma-separated). PLEX_URL/PLEX_PUBLIC_URL are allowed by default.
USE_ANALYTICS	❌	false	Enable anonymous usage analytics (Vercel deployments)
ENABLE_DEBUG	❌	false	Enable verbose debug logging and client-server error mapping
USE_STATIC_FILTERS	❌	false	Skip dynamic filter fetching and use built-in genre/year/rating lists. Useful for very large libraries where filter API calls time out.

[^1]: Can be set to a local file (internal to container) OR external URL. Mostly relevant for Vercel deployments, which uses the Turso integration in the set-up workflow by default where these values are auto-generated and -injected. Can of course be swapped out with a database service provider of choice.

[^2]: Only applicable for providers with authentication (Jellyfin, Plex, Emby). Admin role ownership is tracked per-provider. Defaults to the first user of that provider that logs in (if supported), or matching env vars. Admin capabilities are disabled for providers without built-in authentication (like TMDB).

✳️ = Required conditionally

---

Features (Deep dive)

Session Settings

When you create a session, customize it for your group:

Match Strategies

• Two or More: Any two people liking the same content creates a match

  • Best for: Larger groups where majority rules
  • Finding: Quick results, more options

• Unanimous: Everyone must like it for a match

  • Best for: Smaller groups wanting guaranteed crowd-pleasers
  • Finding: Fewer but higher-quality matches

Session Restrictions

• Max Likes: Limit right swipes per person

  • Forces thoughtful, selective choices
  • Prevents mindless approval

• Max Nopes: Limit left swipes per person

  • Stops serial negativity
  • Encourages open-mindedness

• Max Matches: Auto-stop when you have enough options

  • Perfect for when you just need 3-4 solid picks

Guest Lending (Account Sharing)

How it works:

1. Host enables "Guest Lending" in settings
2. Guest joins session with just a name - no account needed
3. Swiparr uses the host's credentials to fetch content
4. Guest gets a unique ID, their swipes are tracked separately
5. Guests cannot access host account or modify settings

Security note: Host credentials are stored server-side and encrypted at rest using AUTH_SECRET while Guest Lending is enabled. See "Generating AUTH_SECRET" in Security & Privacy.

Perfect for: Movie nights with friends who don't have media servers

Admin Role

Automatically Assigned: First user to log in for each provider becomes that provider's admin.

Manual Assignment: Set ADMIN_USERNAME (global) or [PROVIDER]_ADMIN_USERNAME (e.g., JELLYFIN_ADMIN_USERNAME) environment variables.

Admin Privileges:

• Configure included media libraries for the provider
• Manage global provider settings
• Override session restrictions
• Access admin dashboard (only for providers with authentication)

---

Provider Flexibility: Two Modes

Server Lock Mode

PROVIDER_LOCK=true

One provider, admin-controlled

• Admin configures ONE provider in environment variables
• All users automatically use this provider
• Best for: Families, roommates, shared media servers

BYOP Mode

PROVIDER_LOCK=false

Bring Your Own Provider

• Each user connects their own provider during onboarding
• Users can switch providers anytime
• Best for: Users with different media servers, and/or you have none

---

Security & Privacy

• Generating AUTH_SECRET (optional):

# macOS and Linux
openssl rand -base64 32

Windows users can use https://generate-secret.vercel.app/32.

• Encrypted Sessions: iron-session with secure, encrypted cookies
• Encrypted Guest Lending Tokens: host access tokens are encrypted at rest when Guest Lending is enabled
• Scoped Access: Guests can only swipe, no account access
• Data Ownership: Self-hosted = your data stays on your server
• Provider Isolation: No credential sharing in BYOP mode
• CORS Protection: Configured for safe media server integration
• Security Headers: X-Content-Type-Options, X-XSS-Protection, CSP, Referrer-Policy
• Network Safety: Private/LAN provider URLs are blocked by default; enable via ALLOW_PRIVATE_PROVIDER_URLS
• Mode Awareness: Env-configured providers are trusted when PROVIDER_LOCK=true; user-supplied URLs are checked

---

Contributing

Swiparr is now open for contributions!

How to Contribute

1. Start with Discussion - Propose changes before coding
   • [